命令行界面（CLI）

页面摘要： Strapi 自带功能完备的命令行界面（CLI），可让你在数秒内搭建并管理项目。CLI 同时兼容 yarn 和 npm 包管理器。

本页中的 Strapi CLI 命令按类别分组如下：

通用注意事项

建议仅在本地安装 Strapi，这要求为以下所有 strapi 命令添加用于项目初始化的包管理器前缀（例如 npm run strapi help 或 yarn strapi help），或使用专门的 Node 包执行器（例如 npx strapi help）。

ℹ️ 已从 Strapi 5 中移除的 Strapi v4 CLI 命令：

Strapi v4 中的 strapi install、strapi uninstall、strapi new 和 strapi watch-admin 命令已在 Strapi 5 中移除：

Security defaults for new projects

使用 create-strapi-app 搭建的项目，会在生成的 config/ 文件和 .env 中预配置经过安全加固的默认值：

所有默认值都可以在相应的配置文件中调整，以满足项目的需求。

Development

这些命令用于在开发过程中启动和构建你的 Strapi 应用程序。

strapi develop

别名：dev

启动启用自动重新加载的 Strapi 应用程序。

Strapi 在运行时修改/创建文件，并在创建新文件时需要重启。为此，strapi develop 会添加一个文件监视器，并在必要时重启应用程序。

Strapi 还会添加中间件以支持管理面板的 HMR（热模块替换）。这让你能够在无需重启应用程序或运行单独服务器的情况下自定义管理面板。

strapi develop
options: [--bundler | --open | --no-watch-admin | --no-build-admin | --polling | --debug | --silent]

• strapi develop --bundler [bundler]

  选择管理面板构建所用的打包工具（vite 或 webpack）。

• strapi develop --open

  以启用自动重新加载的方式启动应用程序，并打开默认浏览器显示正在运行的管理面板。

• strapi develop --no-watch-admin

  当管理面板代码发生更改时，阻止服务器自动重新加载。

• strapi develop --no-build-admin

  当启用 --no-watch-admin 时，阻止构建管理面板。

• strapi develop --polling

  监视网络目录中的文件更改。

• strapi develop --debug

  启用调试模式并输出详细日志。

• strapi develop --silent

  抑制日志输出。

• strapi develop --install-deps

  自动安装缺失的管理面板对等依赖（react、react-dom、react-router-dom、styled-components）。默认启用。

• strapi develop --no-install-deps

  跳过缺失的管理面板对等依赖的自动安装，若有任何依赖缺失则立即失败。

strapi start

启动禁用自动重新加载的 Strapi 应用程序。

该命令用于在没有重启和文件写入的情况下运行 Strapi 应用程序，主要用于生产环境。

某些功能（例如内容类型构建器）在 strapi start 模式下会被禁用，因为它们需要重启应用程序。start 命令可以前置 环境变量 来自定义应用程序的启动。

strapi build

构建你的管理面板。

strapi build

strapi console

启动服务器并实时在你的应用程序中执行命令。

strapi console

该 console 命令会编译并加载你的应用程序，在后台启动服务器，然后打开一个 Node.js REPL。REPL 会基于你的应用程序名称提供提示符，并通过全局 strapi 对象让你访问所有 Strapi API。连续按两次 Ctrl-C 关闭 REPL 即可优雅地停止服务器。

可用的辅助方法

全局 strapi 对象暴露了以下 getter 和方法，用于与你的应用程序交互：

• strapi.services 和 strapi.service(uid) 用于使用 services

• strapi.controllers 和 strapi.controller(uid) 用于调用 controllers

• strapi.contentTypes 和 strapi.contentType(uid) 用于检查 content-types

• strapi.components 用于列出组件

• strapi.policies 和 strapi.policy(name) 用于 policies

• strapi.middlewares 和 strapi.middleware(name) 用于 middlewares

• strapi.plugins 和 strapi.plugin(name) 用于插件

• strapi.hooks 和 strapi.hook(name) 用于 hooks

• strapi.apis 和 strapi.api(name) 用于 API

• strapi.db 用于通过 Query Engine API 直接查询数据库，例如：

  await strapi.db.query('api::article.article').findMany();
  

利用此环境测试代码并检查你的项目，可直接访问所有 Strapi API。

Cloud

这些命令用于与 Strapi Cloud 交互。详情请参阅 Cloud CLI 文档。

strapi login

登录到 Strapi Cloud（请参阅 Cloud CLI 文档）。

strapi link

将本地项目关联到现有的 Strapi Cloud 项目（请参阅 Cloud CLI 文档）。

strapi deploy

将已关联的本地项目部署到 Strapi Cloud（请参阅 Cloud CLI 文档）。

strapi logout

从 Strapi Cloud 注销（请参阅 Cloud CLI 文档）。

Data management

这些命令用于在 Strapi 实例之间导出、导入和传输数据。

strapi export

导出你的项目数据。默认设置会创建一个 .tar 文件，使用 gzip 压缩，并使用 aes-128-ecb 加密。

strapi export

归档中包含 configuration、entities、links、schemas 等文件夹，数据以 JSON lines 文件存储。使用 --no-encrypt --no-compress 可生成一个可读的 .tar 文件，便于检查或转换为其他格式。

导出的文件会自动按照 export_YYYYMMDDHHMMSS 格式，使用当前日期和时间戳命名。你也可以改用 -f 或 --file 标志指定文件名。下表列出了所有可用的命令行标志选项：

示例

使用自定义文件名导出数据（myData.tar.gz.enc）：

strapi export -f myData

导出不加密的数据：

strapi export --no-encrypt

以未打包的目录形式导出数据：

strapi export --format dir --no-encrypt -f my-export

strapi import

导入数据 到你的项目。导入的数据必须来自另一个 Strapi 应用程序。你必须传入 --file 选项来指定导入操作所用的文件或目录。

strapi import

该命令接受由 strapi export 生成的归档（.tar、.tar.gz、.tar.gz.enc）以及解包后的导出目录。对于归档导入，压缩与加密方式会根据文件名自动识别。当 -f 指向目录时，会自动跳过加密与压缩。

示例

导入数据并传入加密密钥：

strapi import -f your-filepath-and-filename --key my-key

从解包后的导出目录导入：

strapi import -f ./my-export

strapi transfer

在 2 个 Strapi 实例之间传输数据。该命令主要用于本地实例与远程实例之间，或两个远程实例之间。transfer 命令需要一个传输令牌（Transfer token），该令牌在目标实例的管理面板中生成。有关创建传输令牌的详细说明，请参阅 用户指南。

| --force | 对所有提示自动回答“是”，包括可能具有破坏性的请求，并以非交互方式运行。 | | --exclude | 使用逗号分隔的数据类型排除数据。可用类型包括：content、files、config 和 media-library（同时排除上传的二进制文件和上传内容类型的记录）。 | | --only | 仅包含指定的数据。可用类型包括：content、files 和 config。 | | --exclude-content-types | 以逗号分隔的内容类型 UID 列表，用于排除。与被排除类型相关的实体记录和关联链接都会被跳过。 | | --only-content-types | 以逗号分隔的内容类型 UID 列表，仅包含这些类型。只有所列类型的实体记录和关联链接会被传输。 | | --throttle | 以毫秒为单位的时间，用于在每次传输的实体之间注入人为延迟。 | | --no-checksums | 禁用针对资源的端到端 SHA-256 校验和验证。当源实例和目标实例都支持时，默认启用校验和验证。 | | --verbose | 启用详细日志。 | | -h, --help | 显示 strapi transfer 的命令。 |

示例

strapi transfer --to http://example.com/admin --to-token my-transfer-token

Project information

这些命令用于显示项目详情、管理遥测数据以及显示已安装的版本。

strapi report

打印对调试有用、并在报告问题时所需的调试信息。

示例

要在输出中包含项目 UUID 和依赖：

strapi report --uuid --dependencies

要记录所有内容，请使用 --all 选项：

strapi report --all

strapi telemetry:disable

禁用项目的数据收集（请参阅 使用信息）。

strapi telemetry:disable

strapi telemetry:enable

在禁用后重新启用项目的数据收集（请参阅 使用信息）。

strapi telemetry:enable

strapi version

打印当前已安装的 Strapi 版本。

如果 Strapi 已全局安装，该命令会输出当前全局安装的版本；如果命令是从包含 Strapi 项目的某个文件夹运行的，则会输出该项目内 Strapi 的当前版本。

strapi version

strapi help

列出 CLI 命令。

strapi help

Configuration

这些命令用于转储和恢复应用程序已存储的配置。

strapi configuration:dump

别名：config:dump

将配置转储到文件或 stdout，以帮助你迁移到生产环境。

转储格式为 JSON 数组。

Options:
  -f, --file <file>  Output file, default output is stdout
  -p, --pretty       Format the output JSON with indentation and line breaks (default: false)

示例

• strapi configuration:dump -f dump.json
• strapi config:dump --file dump.json
• strapi config:dump > dump.json

以上示例均等效。

strapi configuration:restore

别名：config:restore

将配置转储恢复到你的应用程序中。

输入格式必须为 JSON 数组。

strapi configuration:restore

Options:
  -f, --file <file>          Input file, default input is stdin
  -s, --strategy <strategy>  Strategy name, one of: "replace", "merge", "keep". Defaults to: "replace"

示例

• strapi configuration:restore -f dump.json
• strapi config:restore --file dump.json -s replace
• cat dump.json | strapi config:restore
• strapi config:restore < dump.json

以上示例均等效。

策略

运行恢复命令时，你可以从三种不同策略中选择：

• replace：会创建缺失的键并替换已有的键。
• merge：会创建缺失的键，并将已有键与新值合并。
• keep：会创建缺失的键，并保持已有键不变。

Administration

这些命令用于管理 Strapi 管理面板的管理员账户。

strapi admin:create-user

别名 admin:create

创建一个管理员。

管理员名、姓、电子邮件和密码可以通过以下方式提供：

• 作为选项传入
• 或在调用命令时不传入任何选项，以交互方式设置。

示例

strapi admin:create-user --firstname=Jane --lastname=Doe --email=chef@strapi.io --password=foobar1234

选项

strapi admin:list-users

别名 admin:list

显示一个表格，列出所有管理员账户，包括其 ID、电子邮件、名和姓、激活状态、封禁状态以及分配的角色。

strapi admin:list-users

strapi admin:active-user

别名 admin:active

设置管理员账户的激活状态。电子邮件和激活状态可以作为选项传入，也可以在调用命令时不带选项时以交互方式提供。

示例

strapi admin:active-user --email=chef@strapi.io --active=true

选项

strapi admin:block-user

别名 admin:block

设置管理员账户的封禁状态。电子邮件和封禁状态可以作为选项传入，也可以在调用命令时不带选项时以交互方式提供。

示例

strapi admin:block-user --email=chef@strapi.io --block=true

选项

strapi admin:reset-user-password

别名 admin:reset-password

重置管理员用户的密码。

你可以将电子邮件和新密码作为选项传入，也可以在调用命令时不传入选项时以交互方式设置。

示例

strapi admin:reset-user-password --email=chef@strapi.io --password=foobar1234

选项

strapi admin:delete-user

别名 admin:delete

删除现有的管理员账户。电子邮件可以作为选项传入，也可以在调用命令时不带选项时以交互方式提供。删除前会显示一个交互式确认提示。

示例

strapi admin:delete-user --email=chef@strapi.io

选项

Code generation

这些命令用于搭建 API、内容类型以及其他项目文件。

strapi generate

生成 API、controllers、content-types、policies、middlewares、services 以及 migrations。

strapi generate

该命令会显示一个交互式菜单，包含以下选项：

• api - 生成包含控制器和服务的全新 API
• controller - 生成新的控制器
• content-type - 生成包含模式（schema）的新内容类型
• policy - 生成新的策略
• middleware - 生成新的中间件
• migration - 生成新的数据库迁移
• service - 生成新的服务

生成器会自动检测 TypeScript 或 JavaScript，并创建具有正确扩展名（.ts 或 .js）的文件。 生成的文件包含带注释的示例。单数名称和复数名称必须不同，并使用 kebab-case 格式 。

API 生成器

创建一个包含 controller 和 service 文件的 API。

生成的文件： controllers/[name].js|ts, services/[name].js|ts, and routes/[name].js|ts（仅标准 API）

内容类型生成器

创建一个包含可选 API 文件的内容类型模式（schema）。

可用的属性类型

生成的文件

• content-types/[name]/schema.json
• controllers/[name].js\|ts
• services/[name].js\|ts
• routes/[name].js\|ts |

文件夹分配

生成器还会询问是否将该内容类型添加到某个文件夹，以便在管理面板中对其进行组织（请参阅 使用文件夹组织内容类型）：

1. 对 是否将此内容类型添加到文件夹？ 问题回答“是”。
2. 选择一个已有文件夹，或选择 创建新文件夹 并输入新文件夹的名称。

该分配会写入项目的 content structure file（内容结构文件），已存在的文件夹不会被改动。

新文件夹会根据所生成内容类型的种类，创建在 Collection types（集合类型）或 Single types（单一类型）分类的根目录下。为插件生成的内容类型不会被添加到文件夹中。

控制器生成器

创建一个具有基本操作结构的 controller 文件。

生成的文件： controllers/[name].js|ts

服务生成器

创建一个具有基本结构的 service 文件。

生成的文件： services/[name].js|ts

策略生成器

创建一个用于访问控制的 policy 文件。

生成的文件： policies/[name].js|ts

中间件生成器

创建一个用于处理请求的 middleware 文件。

生成的文件： middlewares/[name].js|ts

迁移生成器

创建一个带时间戳的 migration 文件。

生成的文件： database/migrations/[timestamp].[name].js|ts

配置选项

根据所选的要生成的 Strapi 元素，strapi generate 交互式 CLI 可能会提供各种配置选项：

目标位置选择

在创建内容类型、控制器、策略、中间件或服务时，你可以选择其目标位置：

内容类型的特定选项

在创建内容类型时，你可以选择创建集合类型或单一类型（两者区别请参阅 内容类型构建器 文档）：

你还需要定义各种类型的名称。下表说明了它们之间的区别。只需手动定义显示名称，然后按 Enter 即可接受单数名称和复数名称的默认建议名称。单数名称和复数名称对于 API 端点非常重要（详见 REST API 文档）：

strapi openapi generate

为你的 Strapi 应用程序生成 OpenAPI 规范。

strapi openapi generate

示例

Yarn

# Generate OpenAPI specification (default)
yarn strapi openapi generate

# Generate with custom output path
yarn strapi openapi generate --output ./docs/api-spec.json

NPM

# Generate OpenAPI specification (default)
npm run strapi openapi generate

# Generate with custom output path
npm run strapi openapi generate -- --output ./docs/api-spec.json

strapi templates:generate

根据当前 Strapi 项目创建一个模板。

strapi templates:generate <path>

• strapi templates:generate <path>

  在 <path> 处生成 Strapi 模板

  示例：strapi templates:generate ../strapi-template-name 会将所需的文件和文件夹复制到 ../strapi-template-name 内部的 template 目录中

strapi ts:generate-types

为项目模式（schema）生成 TypeScript 类型定义。

strapi ts:generate-types

• strapi ts:generate-types --debug

  启用调试模式生成类型定义，并显示所生成模式的详细表格。

• strapi ts:generate-types --silent 或 strapi ts:generate-types -s

  启用静默模式生成类型定义，完全去除终端中的所有日志。不能与 debug 同时使用。

• strapi ts:generate-types --out-dir <path> 或 strapi ts:generate-types -o <path>

  指定输出目录来生成类型定义，文件将创建在该目录中。

Listing

这些命令用于列出 Strapi 项目中已注册的元素。

strapi routes:list

显示所有可用 routes 的列表。

strapi routes:list

strapi policies:list

显示所有已注册 policies 的列表。

strapi policies:list

strapi middlewares:list

显示所有已注册 middlewares 的列表。

strapi middlewares:list

strapi content-types:list

显示所有现有 content-types 的列表。

strapi content-types:list

strapi hooks:list

显示所有可用 hooks 的列表。

strapi hooks:list

strapi controllers:list

显示所有已注册 controllers 的列表。

strapi controllers:list

strapi services:list

显示所有已注册 services 的列表。

strapi services:list