升级工具（Upgrade tool）

页面摘要： 升级工具是一个 CLI 命令，它通过更新依赖项并对代码库应用 codemods（代码自动修改脚本）来将 Strapi 应用自动升级到新版本。

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

运行升级工具会触发应用依赖项的更新与安装，并执行一系列 codemods ，这些脚本会根据目标版本之前引入的破坏性变更自动修改应用代码库。

升级工具是一个 Strapi 软件包，可通过 CLI 运行。

适用范围

虽然升级工具有助于升级应用和插件，但它并不涵盖所有方面。

:white_check_mark: 升级工具支持：

  • 更新项目的依赖项
  • 对现有文件应用自动代码转换
  • 为项目安装或重新安装正确的依赖项

:x: 升级工具不支持：

  • 通过添加、删除或移动文件和目录来修改文件树
  • 迁移应用的数据。这部分由 Strapi 数据库迁移负责处理
WARNING

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

版本类型

Strapi 的版本号遵循 语义化版本（semantic versioning） 规范：

版本号说明

  • 第一个数字为 主（major） 版本号。
  • 第二个数字为 次（minor） 版本号。
  • 第三个数字为 修订（patch） 版本号。

升级工具允许升级到主版本、次版本或修订版本。

升级工具的具体行为取决于当前已有的最新版本以及所运行的命令。

例如，假设最新的 Strapi v4 版本为 v4.25.9：

我的 Strapi 应用当前处于…如果我运行…我的 Strapi 应用将被升级到…
v4.25.1npx @strapi/upgrade patchv4.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.0.0 | | v4.14.1 | npx @strapi/upgrade latest | v5.1.2

会出现一个确认提示，以确保主版本号的跃升是用户预期的行为。 |

升级到新版本

WARNING

在运行升级流程之前，请务必已对代码库和数据库创建备份。

升级到主版本

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

npx @strapi/upgrade major

在升级过程中，应用的依赖项会被更新并安装，同时会执行相关的 codemods。

NOTE

如果你的应用尚未运行当前主版本下的最新次版本和修订版本，则 major 升级会被阻止，你需要先升级到当前主版本下的最新 次.修订 版本。这意味着从 v4.14.4 升级到 v5.0.0 是一个两步过程，因为最新的 v4 版本为 v4.16.2。

升级到次版本

使用 minor 参数运行升级工具，将项目升级到 Strapi 的最新次版本和修订版本：

npx @strapi/upgrade minor

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

升级到修订版本

使用 patch 参数运行升级工具，将项目升级到当前次版本和主版本下的最新修订版本：

npx @strapi/upgrade patch

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

升级到最新版本

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

npx @strapi/upgrade latest

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

NOTE

如果检测到 major 版本升级，升级工具会显示一个确认提示，以确保该变更是用户预期的。

如果你不希望进行主版本跃升，请参阅 次版本升级。

升级到特定版本

使用 to 参数并后接目标版本运行升级工具，将项目升级到该特定的已发布 Strapi 版本：

npx @strapi/upgrade to 5.42.0

当 latest 解析出的版本被你的 registry（注册表）策略所阻止时，可使用 to。例如，你的 .npmrc 可能设置了 min-release-age（新发布版本可安装前的延迟）以降低供应链风险。在这种情况下，最新发布的版本尚不可安装，因此你可以改为指定一个较旧的版本。

对于预发布版本，可传入 --codemods-target 选项来选择运行哪一组 codemods。其默认值为目标版本的 主.次.修订 部分：

npx @strapi/upgrade to 5.0.0-beta.951 --codemods-target 5.0.0
NOTE

to 命令会跳过安全检查——该检查要求在主版本升级前，项目必须处于当前主版本的最新修订版本。此命令适用于明确知道自己想要定位到哪个版本的用户。

仅运行 codemods

使用 codemods 参数运行升级工具，可执行一个工具，用于选择要运行的 codemods。使用此命令时，仅会运行 codemods，不会更新或安装依赖项。

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

npx @strapi/upgrade codemods ls

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

npx @strapi/upgrade codemods run

要仅运行某个特定的 codemod，可在 run 后接通过 ls 命令查到的 UID：

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

选项

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

OptionDescriptionDefault
-n, --dry模拟 升级，但不更新任何文件false
-d, --debug在调试模式下获取更多日志false
-s, --silent不记录任何日志false
-p, --project-path <project-path>Strapi 项目的路径-
-y, --yes对所有提示自动回答“是”false

以下选项既可以单独与 npx @strapi/upgrade 命令一起运行，也可以与 npx @strapi/upgrade [major|minor|patch] 命令一起运行：

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

模拟升级而不更新任何文件（dry run）

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

Examples:

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

为 Strapi 应用文件夹指定路径

传入 -p 或 --project-path 选项并后接一个有效路径时，你可以指定 Strapi 应用所在的文件夹。

Example:

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

获取当前版本

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

Example:

$ npx @strapi/upgrade -V
4.15.1

获取详细的调试信息

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

npx @strapi/upgrade --debug

静默执行升级

传入 --silent 选项（或其简写 -s）时，工具会在不提供任何日志的情况下执行升级：

npx @strapi/upgrade --silent

对所有提示回答“是”

传入 --yes 选项（或其简写 -y）时，工具会对所有提示自动回答“是”：

npx @strapi/upgrade --yes`

获取帮助

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

Examples:

升级工具的常规帮助

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

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

Commands:
 latest [options]  Upgrade to the latest available version of Strapi
 major [options]   Upgrade to the next available major version of Strapi
 minor [options]   Upgrade to ...
 patch [options]   Upgrade to ...
to [options] <target> Upgrade to a specific version of Strapi
 help [command]    Print options for a specific command

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