升级工具

¥Upgrade tool

升级工具帮助 Strapi 用户将其 Strapi 应用依赖和代码升级到特定版本。

¥The upgrade tool assists Strapi users in upgrading their Strapi application dependencies and code to a specific version.

运行升级工具会触发应用依赖的更新、它们的安装以及一系列代码修改 的执行，这些代码修改会根据目标版本之前引入的重大更改自动编辑应用代码库。

¥Running the upgrade tool triggers the update of the application dependencies, their installation, and the execution of a series of codemods that automatically edit the application codebase according to the breaking changes introduced up until the targeted version.

升级工具是一个 Strapi 包，可以从 CLI 运行。

¥The upgrade tool is a Strapi package and can be run from the CLI.

范围

¥Scope

虽然升级工具有助于升级应用和插件，但它并未涵盖其各个方面。

¥While the upgrade tool helps upgrade applications and plugins, it doesn't cover every aspect of it.

✅升级工具支持：

¥✅ The upgrade tool supports:

• 更新项目的依赖

  ¥Updating the project's dependencies

• 将自动代码转换应用于现有文件

  ¥Applying automatic code transformation to existing files

• 为项目安装或重新安装正确的依赖

  ¥Installing or re-installing the correct dependencies for the project

❌升级工具不支持：

¥❌ The upgrade tool doesn't support:

• 通过添加、删除或移动文件和目录来修改文件树​​

  ¥Modifying the file tree by adding, removing or moving files and directories

• 迁移应用的数据。这由 Strapi 数据库迁移处理

  ¥Migrating the application's data. This is handled by Strapi database migrations

警告

升级工具完成执行后，强烈建议在重新运行应用或插件之前检查所做的修改。

¥After the upgrade tool completes its execution, it is strongly recommended to review the modifications made before re-running the app or plugin.

版本类型

¥Version types

Strapi 版本号遵守 语义版本控制 约定：

¥Strapi version numbers respect the semantic versioning conventions:

• 第一个数字是主版本号。

  ¥The first number is the major version number.

• 第二个数字是次要版本号。

  ¥The second number is the minor version number.

• 第三个数字是补丁版本号。

  ¥The third number is the patch version number.

升级工具允许升级到 major、minor 或 patch 版本。

¥The upgrade tool allows upgrading to a major, minor, or patch version.

或者，你可以选择升级到 latest 可用版本。

¥Alternatively, you can choose to upgrade to the latest available version.

升级工具的作用取决于三件事：

¥What the upgrade tool does depends on three things:

• 项目 Strapi 版本

  ¥the project Strapi version

• Strapi 的最新可用版本

  ¥the latest available version of Strapi

• 你运行的命令。

  ¥the command you run.

例如，如果最新的 Strapi v4 版本是 v4.25.9，而最新的 Strapi v5 版本是 v5.1.2：

¥For instance, if the latest Strapi v4 version is v4.25.9, and the latest Strapi v5 version is v5.1.2:

我的 Strapi 应用目前正在……	如果我运行...	我的 Strapi 应用将升级到……
v4.25.1	npx @strapi/upgrade patch	v4.25.9 （因为 v4.25.9 是 v4.25 次要版本的最新补丁版本）
v4.14.1	npx @strapi/upgrade minor	v4.25.9
v4.14.1	npx @strapi/upgrade major	没什么。 我首先需要运行 npx @strapi/upgrade minor 才能升级到 v4.25.9。
v4.25.9	npx @strapi/upgrade major	v5.1.2
v4.14.1	npx @strapi/upgrade latest	v5.1.2 出现确认提示，以确保主要版本升级是有意为之。

升级到新版本

¥Upgrade to a new version

警告

在运行升级过程之前，请确保你已经创建了代码库和数据库的备份。

¥Before running the upgrade process, make sure you've created a backup of your codebase and database.

升级到主要版本版本

¥Upgrade to a major version

使用 major 参数运行升级工具，将项目升级到下一个主要 Strapi 版本的最新版本：

¥Run the upgrade tool with the major parameter to upgrade the project to the latest release of the next major Strapi version:

npx @strapi/upgrade major

在升级过程中，将更新和安装应用依赖，并执行相关的代码修改（如果有）。

¥During the upgrade process, the application dependencies are updated and installed, and the related codemods are executed (if any).

注意

如果你的应用尚未运行当前主要版本中的最新次要版本和补丁版本，则会阻止 major 升级，并且你首先需要升级到当前主要版本中的最新 minor.patch 版本。

¥If your application is not already running the latest minor and patch version in the current major, the major upgrade is prevented, and you will first need to upgrade to the latest minor.patch version in the current major version.

这意味着从 v4.14.4 迁移到 v5.0.0 是一个两步过程，因为最新的 v4 版本是 v4.16.2。

¥This means that moving from v4.14.4 to v5.0.0 is a 2-step process because the latest v4 version is v4.16.2.

升级到小版本

¥Upgrade to a minor version

使用 minor 参数运行升级工具，将项目升级到当前主要版本的最新次要版本和补丁版本 Strapi：

¥Run the upgrade tool with the minor parameter to upgrade the project to the latest minor and patch version of Strapi for the current major:

npx @strapi/upgrade minor

在升级过程中，项目依赖会更新和安装，并执行相关的 codemod（如果有）。

¥During the upgrade process, the project dependencies are updated and installed, and the related codemods are executed (if any).

升级到补丁版本

¥Upgrade to a patch version

使用 patch 参数运行升级工具，将项目升级到 Strapi 当前次要和主要版本中的最新补丁版本：

¥Run the upgrade tool with the patch parameter to upgrade the project to the latest patch version in the current minor and major version of Strapi:

npx @strapi/upgrade patch

在升级过程中，项目依赖会更新和安装，并执行相关的 codemod（如果有）。

¥During the upgrade process, the project dependencies are updated and installed, and the related codemods are executed (if any).

升级到最新版本

¥Upgrade to the latest version

使用 latest 参数运行升级工具，无论当前 Strapi 版本如何，都可以将项目升级到最新可用版本：

¥Run the upgrade tool with the latest parameter to upgrade the project to the latest available version regardless of the current Strapi version:

npx @strapi/upgrade latest

在升级过程中，项目依赖会更新和安装，并执行相关的 codemod（如果有）。

¥During the upgrade process, the project dependencies are updated and installed, and the related codemods are executed (if any).

注意

如果检测到 major 版本升级，升级工具将显示确认提示以确保更改是预期的。

¥If a major version upgrade is detected, the upgrade tool displays a confirmation prompt to make sure the change is intended.

在主要问题不是所需选项的情况下，请参阅 次要升级。

¥In the scenario where the major bump isn't the desired option, see the minor upgrade.

仅运行 codemods

¥Run codemods only

使用 codemods 参数运行升级工具以执行允许选择要执行的代码模式的实用程序。使用此命令，仅运行 codemod，不更新或安装依赖。

¥Run the upgrade tool with the codemods parameter to execute a utility that allows selecting the codemods to be executed. With this command, only the codemods are run, the dependencies are not updated nor installed.

要查看可用 codemods 的列表，请使用 ls 命令：

¥To view a list of the available codemods, use the ls command:

npx @strapi/upgrade codemods ls

要从可用 codemods 列表中选择并运行它们，请使用 run 命令：

¥To select from a list of available codemods and run them, use the run command:

npx @strapi/upgrade codemods run

要仅运行特定的 codemod，请使用 run，后跟从 ls 命令中找到的 UID：

¥To run only a specific codemod, use run followed by a UID found from the ls command:

npx @strapi/upgrade codemods run 5.0.0-strapi-codemod-uid

选项

¥Options

npx @strapi/upgrade [major|minor|patch] 命令可以接受以下选项：

¥The npx @strapi/upgrade [major|minor|patch] commands can accept the following options:

选项	描述	默认
-n, --dry	模拟 升级而不更新任何文件	false
-d, --debug	在调试模式下获取 更多日志	false
-s, --silent	不记录任何内容	false
-p, --project-path <project-path>	路径 到 Strapi 项目	*
-y, --yes	自动 答案 "yes" 到每个提示	false

以下选项可以单独使用 npx @strapi/upgrade 命令或使用 npx @strapi/upgrade [major|minor|patch|latest] 命令运行：

¥The following options can be run either with the npx @strapi/upgrade command alone or with the npx @strapi/upgrade [major|minor|patch|latest] commands:

选项	描述
-V, --version	输出 版本号
-h, --help	打印 命令行选项

模拟升级而不更新任何文件（试运行）

¥Simulate the upgrade without updating any files (dry run)

当传递 -n 或 --dry 选项时，codemods 会在不实际编辑文件的情况下执行。package.json 不会被修改，依赖也不会重新安装。使用此选项可以模拟代码库的升级，在不应用任何更改的情况下检查结果：

¥When passing the -n or --dry option, the codemods are executed without actually editing the files. The package.json will not be modified, and the dependencies will not be re-installed. Using this option allows simulating the upgrade of the codebase, checking the outcomes without applying any changes:

示例：

¥Examples:

npx @strapi/upgrade major --dry
npx @strapi/upgrade minor --dry
npx @strapi/upgrade patch --dry
npx @strapi/upgrade latest --dry

选择 Strapi 应用文件夹的路径

¥Select a path for the Strapi application folder

当传递 -p 或 --project-path 选项后跟有效路径时，你可以指定 Strapi 应用位于哪个文件夹中。

¥When passing the -p or --project-path option followed by a valid path you can specify in which folder the Strapi application is located.

示例：

¥Example:

npx @strapi/upgrade major -p /path/to/the/Strapi/application/folder

获取当前版本

¥Get the current version

传递 --version 选项（或其 -V 简写）时，会记录升级工具的当前版本。

¥When passing the --version option (or its -V shorthand), the current version of the upgrade tool is logged.

示例：

¥Example:

$ npx @strapi/upgrade -V
4.15.1

获取详细的调试信息

¥Get detailed debugging information

当传递 --debug 选项（或其 -d 简写）时，升级工具会在运行时提供更详细的日志：

¥When passing the --debug option (or its -d shorthand), the upgrade tool provides more detailed logs while running:

npx @strapi/upgrade --debug

执行升级静默地

¥Execute the upgrade silently

当传递 --silent 选项（或其 -s 简写）时，该工具会执行升级而不提供任何日志：

¥When passing the --silent option (or its -s shorthand), the tool executes the upgrade without providing any log:

npx @strapi/upgrade --silent

对每个提示回答“是”

¥Answer yes to every prompt

当传递 --yes 选项（或其 -y 简写）时，该工具会自动对每个提示回答 "yes"：

¥When passing the --yes option (or its -y shorthand), the tool automatically answers "yes" to every prompt:

npx @strapi/upgrade --yes`

获取帮助

¥Get help

传递 --help 选项（或其 -h 简写）时，会显示帮助信息，列出可用选项：

¥When passing the --help option (or its -h shorthand), help information is displayed, listing the available options:

示例：

¥Examples:

General help for the upgrade tool

$ npx @strapi/upgrade -h
Usage: upgrade <command> [options]

Options:
 -V, --version    output the version number
 -h, --help       Print command line options

Commands:
 major [options]  Upgrade to ...
 minor [options]  Upgrade to ...
 patch [options]  Upgrade to ...
 latest [options]  Upgrade to ...
 help [command]   Print options for a specific command

Specific help for upgrade major

$ npx @strapi/upgrade major -h
Usage: upgrade major [options]

Upgrade to the next available major version of Strapi

Options:
  -p, --project-path <project-path>  Path to the Strapi project
  -n, --dry                          Simulate the upgrade without updating any files (default: false)
  -d, --debug                        Get more logs in debug mode (default: false)
  -s, --silent                       Don't log anything (default: false)
  -h, --help                         Display help for command
  -y, --yes                          Automatically answer yes to every prompt