升级到 Strapi 5 的分步指南

¥Step-by-step guide to upgrade to Strapi 5

Strapi 的最新主要版本是 Strapi 5。

¥The latest major version of Strapi is Strapi 5.

本页面旨在用作将 Strapi v4 应用升级到 Strapi 5 的分步说明。

¥The present page is meant to be used as step-by-step instructions for upgrading your Strapi v4 application to Strapi 5.

Prerequisites

你的 Strapi v4 应用已在最新的 v4 次要版本和补丁版本上运行。如果不是，请使用 minor 命令运行 升级工具 以访问它：npx @strapi/upgrade minor。

¥Your Strapi v4 application is already running on the latest v4 minor and patch version. If it's not, run the upgrade tool with the minor command to reach it: npx @strapi/upgrade minor.

步骤 1：准备升级

¥Step 1: Get ready to upgrade

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

¥Before getting into the upgrade process itself, take the following precautions:

1. 备份你的数据库：

   ¥Backup your database:

   • 如果你使用默认配置的 SQLite（Strapi 提供的默认数据库），你的数据库文件名为 data.db，位于 Strapi 应用根目录的 .tmp/ 文件夹中。

     ¥If you are using SQLite with the default configuration (the default database provided with Strapi), your database file is named data.db and is located in the .tmp/ folder at the root of your Strapi application.

   • 如果你使用的是其他类型的数据库，请参阅其官方文档（参见 PostgreSQL 文档 和 MySQL 文档）。

     ¥If you are using another type of database, please refer to their official documentation (see PostgreSQL docs and MySQL docs).

   • 如果你的项目托管在 Strapi Cloud 上，你可以手动 创建备份。

     ¥If your project is hosted on Strapi Cloud, you can manually create a backup.

2. 备份你的代码：

   ¥Backup your code:

   • 如果你的代码已使用 git 进行版本控制，请创建一个新的专用分支来运行迁移。

     ¥If your code is versioned with git, create a new dedicated branch to run the migration.

   • 如果你的代码未使用 git 进行版本控制，请备份你的 Strapi v4 代码并将其存储在安全的地方。

     ¥If your code is not versioned with git, create a backup of your working Strapi v4 code and store it in a safe place.

3. 确保你使用的插件与 Strapi 5 兼容。

   ¥Ensure the plugins you are using are compatible with Strapi 5.

为此，请列出你正在使用的插件，然后通过阅读 市场 网站上的专用文档来检查每个插件的兼容性。

¥To do so, list the plugins you are using, then check compatibility for each of them by reading their dedicated documentation on the Marketplace website.

第 2 步：运行自动迁移

¥Step 2: Run automated migrations

Strapi 提供了一种工具来自动执行升级到 Strapi 5 的某些部分：升级工具。

¥Strapi provides a tool to automate some parts of the upgrade to Strapi 5: the upgrade tool.

1. 运行升级工具。

   ¥Run the upgrade tool.

npx @strapi/upgrade major

该命令将执行 Strapi 5 依赖的更新和安装，并运行 codemods 来处理 Strapi 5 带来的一些重大更改。

¥The command will execute the update and installation of the dependencies of Strapi 5, and run the codemods to handle some of the breaking changes that come with Strapi 5.

codemods 将处理以下更改：

¥The codemods will handle the following changes:

Codemod 名称和 GitHub 代码链接	描述
	注释掉生命周期文件以支持 文档服务中间件
	删除根级配置选项（如 ），并将其替换为插件数组中的插件钩子。
	升级 react 和 react-dom 依赖
	升级 react-router-dom 依赖
	升级 styled-components 依赖
	部分处理从 @strapi/helper-plugin 的迁移
	部分处理从实体服务 API 到新文档服务 API 的迁移
	为使用 aws-s3 提供程序的用户将 accessKeyId 和 secretAccessKey 属性封装在 credentials 对象中
	将 sqlite 依赖更新为 better-sqlite3
	转换 @strapi/strapi 导入以使用新的公共接口
	替换或自定义 WYSIWYG 编辑器
	更新实用程序以使用新的公共接口

提示

如果你开发 Strapi 插件，其他 codemods 会处理辅助插件弃用的某些方面。有关更多信息，请参阅 相关重大更改更改。

¥If you develop Strapi plugins, other codemods handle some aspects of the helper-plugin deprecation. See the related breaking change for more information.

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

   ¥Go over the changes made by the upgrade tool to check if you have to manually complete some code updates:

查找 codemods 自动添加到你的代码中的 __TODO__。其中一些可能是在从实体服务 API 迁移到 Strapi 5 中引入的新文档服务 API 时添加的。

¥Look for __TODO__ automatically added to your code by the codemods. Some of them might have been added while migrating from the Entity Service API to the new Document Service API introduced in Strapi 5.

Document Service API

Additional information about the Document Service API can be found in the breaking change entry description, the specific migration guide, and the API reference.

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

¥Step 3: Check and handle manual upgrades

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

¥The following main changes might affect your Strapi application and require you to do some manual actions.

对于每个日志项，请阅读指示的重大更改条目并检查升级工具运行后是否仍需要某些手动操作：

¥For each of them, read the indicated breaking change entry and check if some manual actions are still required after the upgrade tool has run:

1. 数据库迁移：

   ¥Database migration:

   1. 不支持 MySQL v5 👉 参见 重大变更

      ¥MySQL v5 is not supported 👉 see breaking change

   2. 仅支持 better-sqlite3 👉 参见 重大变更

      ¥Only better-sqlite3 is supported 👉 see breaking change

   3. 仅支持 mysql2 👉 参见 重大变更

      ¥Only mysql2 is supported 👉 see breaking change

   4. 生命周期钩子的触发方式不同👉参见 重大变更

      ¥Lifecycle hooks are triggered differently 👉 see breaking change

2. 配置：

   ¥Configuration:

   1. 一些环境变量由服务器配置处理👉参见 重大变更

      ¥Some environment variables are handled by the server configuration 👉 see breaking change

   2. 自定义配置必须满足特定要求👉参见 重大变更

      ¥Custom configuration must meet specific requirements 👉 see breaking change

3. 管理面板自定义：

   ¥Admin panel customization:

   • 辅助插件已被删除👉参见 迁移参考

     ¥The helper-plugin has been removed 👉 see migration reference

👉 最后，查看 重大变更数据库 的其余部分，了解你可能担心的任何边缘情况。

¥👉 Finally, go over the rest of the breaking changes database for any edge case you might be concerned about.

步骤 4：迁移 API 消费方

¥Step 4: Migrate the API consuming side

Strapi 5 已更新 REST 和 GraphQL API。

¥Strapi 5 has updated both the REST and GraphQL APIs.

请按照以下步骤操作，并利用向后兼容性标头和引导式迁移资源，逐步将你的代码更新为 Strapi 5。

¥Follow the steps below and leverage retro-compatibility headers and guided migration resources to gradually update your code for Strapi 5.

迁移 REST API 调用

¥Migrate REST API calls

1. 在仍然需要 attributes 的所有地方启用兼容性标头，方法是在 HTTP 客户端、SDK 和中间件的 REST 调用中添加 Strapi-Response-Format: v4（有关具体示例，请参阅 重大变更条目）。

   ¥Enable the compatibility header everywhere you still expect attributes, by adding Strapi-Response-Format: v4 to REST calls in HTTP clients, SDKs, and middleware (see the breaking change entry for concrete examples).

2. 启用标头后，请审核现有有效负载。捕获代表性响应（包括已填充的关系、组件和媒体），以便验证旧版客户端在过渡期间是否仍然有效。

   ¥While the header is on, audit existing payloads. Capture representative responses (including populated relations, components, and media) so you can verify that legacy consumers keep working during the transition.

3. 通过以下方式更新和测试每个客户端：

   ¥Update and test each client by:

   • 移除 data.attributes 访问权限

     ¥removing data.attributes access,

   • 切换到扁平化有效负载后，

     ¥switching to the flattened payload,

   • 并且在 REST API 之前仅返回数字 id 的地方都采用 documentId。

     ¥and adopting documentId wherever the REST API was previously returning numeric id only.

4. 按端点或使用者禁用兼容性标头：一旦给定客户端的测试通过，就从其请求中移除 Strapi-Response-Format: v4。重复此操作，直到没有使用者依赖于旧版封装器。

   ¥Disable the compatibility header per endpoint or consumer: once tests pass for a given client, remove Strapi-Response-Format: v4 from its requests. Repeat until no consumer depends on the legacy wrapper.

迁移 GraphQL API 调用

¥Migrate GraphQL API calls

1. 通过在 graphql 插件配置中将 v4CompatibilityMode 设置为 true 来启用兼容性标头，以便在重构客户端时客户端可以继续依赖 data.attributes。

   ¥Enable the compatibility header by setting v4CompatibilityMode to true in the graphql plugin configuration, so clients can continue to rely on data.attributes while you refactor them.

2. 请按照 GraphQL 的重大变更条目 的每个步骤操作。这将指导你将 id 替换为 documentId，采用 _connection 查询，移除 attributes，最后切换到 nodes/pageInfo。

   ¥Follow each step of the breaking change entry for GraphQL. This will guide you to swap id for documentId, adopt _connection queries, remove attributes, and finally switch to nodes/pageInfo.

3. 测试 Relay 和非 Relay 查询，方法是：对于不需要 Relay 语义的客户端，移除 _connection 和 data 后，确认分页元数据是否仍然符合预期。

   ¥Test Relay and non-Relay queries by confirming that pagination metadata still matches expectations when you remove _connection and data for clients that do not need Relay semantics.

4. 禁用 v4CompatibilityMode 兼容性标头：在每次查询和变更操作都使用扁平化模式后，将标头设置为 false，以便服务器默认发出 Strapi 5 格式。

   ¥Disable the v4CompatibilityMode compatibility header: after every query and mutation works with the flattened schema, set the header to false so the server emits the Strapi 5 format by default.