strapi-version-upgrade

Strapi 版本升级

将 Strapi 项目升级到目标版本。此技能强制遵循两条硬性规则：

1. 升级前务必检查破坏性变更。 在查看当前版本与目标版本之间适用的破坏性变更之前，切勿运行升级。
2. 务必使用 @strapi/upgrade 工具执行升级。 切勿通过手动编辑 package.json 或直接运行 npm install @strapi/strapi@x 来升级。

请按顺序执行以下步骤。

步骤 1 — 确定当前版本和目标版本

1. 从 package.json 中读取项目当前的 Strapi 版本（dependencies 下的 @strapi/strapi）。如果工作目录中没有 Strapi 项目，请停止并告知用户。

2. 确定最新发布版本：

   npm view @strapi/strapi dist-tags
   

   latest 标签代表最新的稳定版。legacy 通常代表最新的 v4 版本。

3. 确定目标版本。如果用户指定了版本或发布类型（major/minor/patch/latest/具体的 x.y.z），则使用该版本或类型。否则，默认使用 latest 并向用户确认。

4. 使用语义化版本对升级跨度进行分类：比较当前版本与目标版本的 major/minor/patch。只有 major 版本号发生变化时才会引入破坏性变更。 根据定义，minor 和 patch 版本向后兼容。

步骤 2 — 检查破坏性变更（升级前必须执行）

如果可以使用 strapi-docs-mcp 技能 / strapi-docs MCP 服务，请使用它；否则直接获取文档。即使是 patch 升级，也不得跳过此步骤。

如果可以使用 strapi-docs MCP 服务

向其查询当前版本与目标版本之间的破坏性变更，例如：

“从 <current> 升级 Strapi 到 <target> 时有哪些破坏性变更？”

引用破坏性变更的准确标题，并注明哪些变更由 codemod 处理，哪些需要手动处理。

如果无法使用 strapi-docs MCP 服务

直接获取破坏性变更页面（无需身份验证）。优先使用扁平化的 Markdown 格式：

• 主版本迁移（例如 v4 → v5）：https://docs.strapi.io/cms/migration/v4-to-v5/breaking-changes.md

对 .md URL 使用 WebFetch（在任何 docs.strapi.io 页面后添加 .md，即可获取扁平化 Markdown，且不会遗漏标签页或折叠面板中的内容）。如果 .md 页面返回 404，请重试 HTML URL。

提供具体报告 — 扫描代码库

不要只提供文档中的通用列表。对于每项破坏性变更，都要搜索项目自身的源代码，确认哪些变更实际适用，并将摘要整理成针对该项目的清单。具体来说：

• 阅读 src/index.{js,ts}（应用的 register/bootstrap 入口），查找破坏性变更涉及的模式。
• 扫描项目的控制器、服务和路由文件（src/api/**）——升级工具的 codemod 会覆盖常见模式，但自定义逻辑通常会使用被破坏性变更重命名或移除的 API。
• 阅读内容类型架构（src/api/**/content-types/**/schema.json 和 src/components/**），查找受破坏性变更影响的属性——例如类型发生变化的属性，或与新的保留名称/系统名称冲突的属性名称。
• 检查 package.json 和 config/plugins.{js,ts}，确认第三方插件的兼容性是否可能受到影响。

使用每项破坏性变更的标题作为搜索关键词（搜索已移除/重命名的 API、已弃用的选项或保留名称）。报告哪些文件与哪些破坏性变更匹配，让用户准确了解升级会影响哪些内容，以及哪些内容需要手动修复。

报告和关卡

• 相同主版本（升级次版本/补丁版本）： 明确说明没有破坏性变更——破坏性变更数据库仅针对主版本迁移。你仍然执行了检查；请说明这一点。
• 升级主版本： 根据上文的代码库扫描结果，总结适用的破坏性变更，指出哪些由代码修改工具处理，哪些需要手动更新代码，说明任何保留名称冲突（这些冲突可能需要数据库迁移——见第 7 步），然后停止并等待用户明确回复后再继续——不要在同一轮中继续操作。

第 3 步 — 升级前安全检查

提醒用户在升级前备份代码库和数据库（默认 SQLite 数据库为 .tmp/data.db）。升级工具还会将干净的 git 工作树作为可选要求进行检查，因此提交代码并保持工作树干净有助于回滚。

建议先进行一次试运行，以预览变更且不修改文件：

npx @strapi/upgrade <target> --dry

步骤 4 — 检查当前运行的 Node 版本（运行工具之前）

@strapi/upgrade 工具本身是一个 Node CLI：它会使用调用 npx 时所用的 Node 运行，并且声明了与目标 Strapi 相同的 Node 要求。因此，在运行工具之前，当前运行的 Node（而不只是 package.json 中的 engines）必须满足目标版本的范围。如果不满足，升级操作和后续的应用启动都会在不受支持的运行时上进行。

1. 查看当前运行的 Node 版本（node -v）。

2. 查看目标 Strapi 支持的 Node 版本范围：

   npm view @strapi/strapi@<target-x.y.z> engines
   

   （对照文档中建议的该主版本 Node 版本进行确认——Strapi 推荐使用当前活跃的 LTS 版本。）

3. 如果当前运行的 Node 已满足目标版本的范围，请继续执行步骤 5。

4. 如果不满足，必须先升级 Node，再进行升级。 具体操作取决于用户是否有 Node 版本管理器——做决定前先检查是否有版本管理器（检查 PATH 中是否有 nvm、fnm 或 volta，以及仓库中是否有 .nvmrc / .node-version / Volta 字段）：

   • 如果存在版本管理器： 询问用户是否希望你为他们升级 Node 版本，并在进行任何运行时更改前等待他们确认。只有在他们确认后：
     • 选择一个符合目标版本范围的 Node 版本，优先选择目标 Strapi 列出的 LTS 版本。
     • 通过他们的版本管理器切换版本（绝不要全局安装），以便更改可撤销——如果需要回滚，旧版 Strapi 仍可在旧版 Node 上运行。建议在仓库中固定该版本（使用 .nvmrc / .node-version / Volta 字段），以便 CI 和团队成员同步切换。
   • 如果不存在版本管理器： 不要自行尝试更改系统 Node——全局切换运行时存在风险，也无法轻易撤销。相反，告知用户需要自行修正 Node 版本，并建议他们先安装版本管理器（nvm、fnm 或 volta），再选择一个符合目标版本范围的 Node 版本。停止操作，等待他们处理好运行时后再继续。
   • 切换 Node 后不要立即重新安装 node_modules。 此时 package.json 仍固定为旧版 Strapi，因此全新安装会基于新版 Node 重建旧版依赖树；如果两个版本范围完全不重叠（见下文），这可能导致 engines 检查失败，或使原生模块基于错误的 ABI 构建，从而在工具尚未推进升级前就破坏当前可用状态。应在步骤 5 之后进行全新安装，此时工具已将 package.json 改写为目标版本（见步骤 7d）。
   • 如果当前 Node 版本范围与目标 Node 版本范围完全不重叠（例如，当前版本支持 Node 18，而目标版本要求 ≥20），则无法在仍使用旧版运行时的情况下安全地原地切换。安全的顺序是：先在旧版 Node 上，将当前主版本更新到最新补丁版本（运行 npx @strapi/upgrade minor），以便这一步仍可回滚；_然后_将 Node 切换到目标版本范围内；_最后_执行步骤 5 中的主版本升级。只有在该升级操作完成后，才能重新安装依赖。

步骤 5 — 使用升级工具运行升级

从项目根目录运行官方工具。根据目标选择相应的命令形式：

npx @strapi/upgrade latest          # newest stable version
npx @strapi/upgrade major           # next major (requires being on latest patch of current major first)
npx @strapi/upgrade minor           # latest minor+patch in current major
npx @strapi/upgrade patch           # latest patch in current minor
npx @strapi/upgrade to <x.y.z>      # a specific published version

注意：

• major 有门槛：项目必须已处于当前主版本的最新补丁版本。如果不是，请先运行 minor，然后再运行 major。
• 如果注册表策略（例如 .npmrc 中的 min-release-age）阻止使用 latest，或者用户需要指定精确版本，请使用 to <x.y.z>。to 会有意跳过主版本安全检查。
• 对于预发布版本，请添加 --codemods-target <x.y.z>。
• 实用标志：-y/--yes（自动确认提示）、-d/--debug（详细输出）、-p/--project-path <path>（非当前工作目录中的项目）。主版本升级时不要使用 -y/--yes——它会自动确认所有提示，包括使用 latest 时的主版本安全提示。除非用户要求无人值守运行，否则请优先使用交互模式（或逐步征得用户批准）。

该工具会更新依赖、安装依赖，并针对目标版本运行 codemod。不要用手动编辑 package.json 或直接运行 npm install 来替代此步骤。

如果安装阶段失败（例如出现 ERESOLVE），请先使用干净的 node_modules 和锁文件重试（rm -rf node_modules package-lock.json && npm install），然后再考虑手动编辑依赖——旧主版本遗留的锁文件是最常见的原因，干净地重新安装通常可以解决问题。

步骤 6 — 修正 engines 字段

升级工具会更新依赖，但不会改动 package.json 的 engines 字段。旧主版本遗留的过时 engines.node 范围可能导致兼容性检查失败，并在升级后阻止 install（npm/yarn/pnpm）。 （这是 package.json 中声明的范围，与步骤 4 中检查的_当前运行的_ Node 版本不同。）

1. 从项目的 package.json 中读取 engines。
2. 复用步骤 4 中目标版本对应的 Node 范围（npm view @strapi/strapi@<target-x.y.z> engines）。
3. 如果项目的 engines.node 范围比目标版本要求的更窄，或与之不兼容，请提出将其替换为目标主版本的正确范围，并在用户确认后应用修改。如果已经兼容，则保持不变。

步骤 7 — 升级后：处理 codemod 未覆盖的内容、插件和迁移

请按顺序执行。每项具有破坏性或会更改代码的操作都必须暂停并征得用户确认——除工具自动应用的内容外，所有更改均由用户决定。

7a — 检查并提出修复 codemod 未覆盖的内容

1. 告知用户在重启应用前检查工具所做的更改（尤其是 codemod 修改和 package.json）。
2. Codemod 覆盖的是常见模式，并非所有情况。将步骤 2 中标记为“手动处理”的破坏性更改，与 codemod 实际修改的代码进行交叉核对。对于仍未处理的内容，询问用户是否希望你尝试修改应用代码，然后**等待用户明确答复；不要在同一轮中开始编辑。**只有用户确认后才能编辑代码，并且要在工具应用 codemod 后再编辑（切勿提前编辑——否则会与 codemod 的修改冲突）。

7b — 升级不兼容的第三方插件

如果任何第三方插件（来自步骤 2 对 package.json/config/plugins 的扫描结果，或由安装/启动错误发现）与目标 Strapi 版本不兼容：

1. 确定支持目标版本的插件版本（npm view <plugin> versions / 插件对 @strapi/strapi 的 peer dependency 范围）。
2. 逐个询问用户是否要升级每个插件——每次插件升级都必须单独确认；切勿在未告知用户的情况下批量升级插件。
3. 应用已确认的版本升级，并重新安装。

7c — 保留名称冲突 → 自定义数据库迁移

如果第 2 步发现某个属性的名称与目标主版本中的新保留名称／系统名称冲突，则必须重命名，而重命名列可能导致数据丢失。此时：

1. 询问用户是否要继续重命名。
2. 如果用户同意，询问是否需要生成数据库迁移，以便在重命名期间保留现有数据。
3. 在写入或运行任何迁移前，必须要求用户明确确认已备份。 迁移将在下次启动时对真实数据库执行，而且重命名无法轻易撤销，因此要请用户确认他们已手动备份数据库——然后停止并等待用户在单独的回复中明确答复“是”；不要在同一轮对话中继续。 不要接受含糊的答复，也绝不能代替用户备份来取代其确认。如果用户尚未备份，就停下来让他们先备份。
4. 只有在用户确认后，才能按照 reference.md 编写迁移（放置位置、排序注意事项、数据安全的重命名、系统列冲突、幂等性、down()）。不要敷衍处理——其中的排序和冲突规则可避免启动失败和静默数据丢失。

7d — 验证

1. 对于主版本升级，请注意：Strapi 内置的数据迁移会在新主版本首次启动时自动运行——升级工具本身不会迁移数据，./database/migrations/ 中的任何自定义迁移也会在那时运行。
2. 如果在第 4 步切换了 Node，现在要进行干净重装——等工具将 package.json 重写为目标版本后再操作，而不是提前操作：rm -rf node_modules && install。原生模块（better-sqlite3、sharp 等）会针对特定的 Node ABI 编译；旧 Node 留下的过时构建是最常见的“换了 Node 就无法启动”故障，也很容易被误判为升级错误。
3. 验证：必要时重新安装，重新构建管理界面，然后启动应用，确认其能正常启动。