升级到 Strapi 5 的分步指南

页面摘要： 按照分步说明将你的 Strapi v4 应用升级到 Strapi 5，包括数据库与代码备份、运行自动化升级工具、处理手动代码更新，以及使用兼容请求头逐步迁移你的 REST 与 GraphQL API 调用。

Strapi 的最新主版本是 Strapi 5。

本页面将作为分步说明，用于把你的 Strapi v4 应用升级到 Strapi 5。

WARNING

你的 Strapi v4 应用已在运行最新的 v4 小版本（minor）和补丁（patch）版本。如果没有，请使用 upgrade tool（升级工具）并带上 minor 命令来达到该版本：npx @strapi/upgrade minor。

第 1 步：准备升级

在进入升级过程本身之前，请采取以下预防措施：

  1. 备份你的数据库：
    • 如果你使用的是默认配置的 SQLite（Strapi 提供的默认数据库），你的数据库文件名为 data.db，位于 Strapi 应用根目录下的 .tmp/ 文件夹中。
    • 如果你使用其他类型的数据库，请参考其官方文档（参见 PostgreSQL 文档 和 MySQL 文档）。
    • 如果你的项目托管在 Strapi Cloud 上，你可以手动 创建备份。
  2. 备份你的代码：
    • 如果你的代码使用 git 进行版本管理，请创建一个专用分支来运行迁移。
    • 如果你的代码未使用 git 进行版本管理，请为正在运行的 Strapi v4 代码创建一份备份，并存放到安全的位置。
  3. 确保你正在使用的插件与 Strapi 5 兼容。

为此，请列出你正在使用的插件，然后通过阅读 Marketplace（市场）网站上各自的专属文档，逐一检查它们的兼容性。

第 2 步：运行自动化迁移

Strapi 提供了一个工具来自动化升级到 Strapi 5 的部分工作：即 upgrade tool（升级工具）。

  1. 运行升级工具。
npx @strapi/upgrade major

该命令将执行 Strapi 5 依赖项的更新与安装，并运行 codemods 来处理随 Strapi 5 带来的一些破坏性变更。

codemods 将处理以下变更：

Codemod 名称与 GitHub 代码链接说明
comment-out-lifecycle-files注释掉生命周期（lifecycles）文件，改用 Document Service Middlewares（文档服务中间件）
dependency-remove-strapi-plugin-i18n移除 i18n 插件依赖，因为 i18n 现已集成到 Strapi 核心中
dependency-upgrade-react-and-react-dom升级 react 与 react-dom 依赖
dependency-upgrade-react-router-dom升级 react-router-dom 依赖
dependency-upgrade-styled-components升级 styled-components 依赖
deprecate-helper-plugin部分处理从 @strapi/helper-plugin 的迁移
entity-service-document-service部分处理从 Entity Service API 到新的 Document Service API 的迁移
s3-keys-wrapped-in-credentials对于使用 aws-s3 提供方（provider）的用户，将 accessKeyId 和 secretAccessKey 属性包裹进一个 credentials 对象中
sqlite3-to-better-sqlite3将 sqlite 依赖更新为 better-sqlite3
strapi-public-interface将 @strapi/strapi 的导入转换为使用新的公共接口（public interface）
use-uid-for-config-namespace在可能的情况下，将 config 的 get/set/has 所用的字符串点号格式替换为 'plugin' 与 'api' 命名空间的 uid 格式
utils-public-interface更新 utils 以使用新的公共接口
TIP

如果你开发 Strapi 插件，还有其他 codemods 会处理 helper-plugin 弃用（deprecation）的某些方面。请参阅 相关的破坏性变更 了解更多信息。

  1. 检查升级工具所做的更改，以确认你是否必须手动完成某些代码更新：

查找 codemods 自动添加到你代码中的 __TODO__。其中一些可能是在从 Entity Service API 迁移到 Strapi 5 引入的新 Document Service API 时添加的。

:::info Document Service API 关于 Document Service API 的更多信息，可在 破坏性变更条目说明、专项迁移指南 以及 API 参考 中找到。 :::

第 3 步：检查并处理手动升级

以下主要变更可能会影响你的 Strapi 应用，并要求你执行一些手动操作。

针对每一项，请阅读所指明的破坏性变更条目，并确认在升级工具运行之后是否仍需要手动操作：

  1. 数据库迁移：
    1. 不再支持 MySQL v5 👉 参见 破坏性变更
    2. 仅支持 better-sqlite3 👉 参见 破坏性变更
    3. 仅支持 mysql2 👉 参见 破坏性变更
    4. 生命周期钩子（lifecycle hooks）的触发方式不同 👉 参见 破坏性变更
  2. 配置：
    1. 部分环境变量由服务器配置处理 👉 参见 破坏性变更
    2. 自定义配置必须满足特定要求 👉 参见 破坏性变更
  3. 管理面板自定义：

👉 最后，请通读 破坏性变更数据库 的其余部分，查看你可能关心的任何边缘情况。

第 4 步：迁移 API 消费侧

Strapi 5 已更新 REST 与 GraphQL 两套 API。

请遵循以下步骤，并借助向后兼容（retro-compatibility）请求头与引导式迁移资源，逐步更新你的代码以适配 Strapi 5。

迁移 REST API 调用

  1. 在你仍期望返回 attributes 的所有位置启用兼容请求头，方法是：在 HTTP 客户端、SDK 以及中间件发出的 REST 调用中添加 Strapi-Response-Format: v4（具体示例参见 破坏性变更条目）。
  2. 在启用请求头期间，审计现有的负载（payload）。捕获有代表性的响应（包括联表加载（populated）的关系、组件和媒体），以便你验证遗留消费方在过渡期间仍能正常工作。
  3. 通过以下方式更新并测试每个客户端：
    • 移除对 data.attributes 的访问，
    • 切换到扁平化的负载，
    • 并在 REST API 之前仅返回数字型 id 的位置，采用 documentId。
  4. 按端点或消费方禁用兼容请求头：一旦某个给定客户端的测试通过，就从它的请求中移除 Strapi-Response-Format: v4。重复此过程，直到没有任何消费方依赖遗留包装器。

迁移 GraphQL API 调用

  1. 通过在 graphql 插件配置中将 v4CompatibilityMode 设为 true 来启用兼容请求头，这样在重构客户端代码期间，客户端可以继续依赖 data.attributes。
  2. 遵循 GraphQL 破坏性变更条目 的每一步。它将引导你用 documentId 替换 id、采用 _connection 查询、移除 attributes，并最终切换到 nodes/pageInfo。
  3. 通过确认在移除不需要 Relay 语义的客户端所用的 _connection 和 data 后，分页元数据仍然符合预期，来测试 Relay 与非 Relay 查询。
  4. 禁用 v4CompatibilityMode 兼容请求头：在每一个查询（query）与变更（mutation）都能使用扁平化模式正常工作后，将该请求头设为 false，这样服务器默认就会发出 Strapi 5 格式。