Skip to main content

升级到 Strapi 5 的分步指南

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

Strapi 的最新主要版本是 Strapi 5，目前作为候选发布版本 (RC) 提供，尚未提供稳定版本。

¥The latest major version of Strapi is Strapi 5, which is currently provided as a Release Candidate (RC) version, not as a stable version yet.

本页面旨在用作将 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.

请确保你的数据库条目未使用保留名称（请参阅相关的 重大更改页面）。

¥ Please ensure your database entries are not using reserved names (see the related breaking change page).

  1. 备份你的代码：

    ¥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.

  2. 确保你使用的插件与 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 代码链接描述
comment-out-lifecycle-files注释掉生命周期文件以支持 文档服务中间件
dependency-remove-strapi-plugin-i18n删除根级配置选项（如 ），并将其替换为插件数组中的插件钩子。
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部分处理从实体服务 API 到新文档服务 API 的迁移
s3-keys-wrapped-in-credentials为使用 aws-s3 提供程序的用户将 accessKeyId 和 secretAccessKey 属性封装在 credentials 对象中
sqlite3-to-better-sqlite3将 sqlite 依赖更新为 better-sqlite3
strapi-public-interface转换 @strapi/strapi 导入以使用新的公共接口
use-uid-for-config-namespace替换或自定义 WYSIWYG 编辑器
utils-public-interface更新实用程序以使用新的公共接口
提示

如果你开发 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.

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

    ¥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:

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

¥ 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 flags and guided migration resources to gradually update your code for Strapi 5.

迁移 REST API 调用​

¥Migrate REST API calls

  1. 通过设置 Strapi-Response-Format: v4 标头来启用追溯兼容性标志。

    ¥Enable the retro-compatibility flag by setting the Strapi-Response-Format: v4 header.

  2. 仅在专用 REST API 的重大变更条目 的指导下更新你的查询和修改。

    ¥Update your queries & mutations only, guided by the dedicated breaking change entry for REST API.

  3. 验证你的客户端是否正常运行。

    ¥Validate that your client is running correctly.

  4. 通过删除 Strapi-Response-Format: v4 标头禁用 retro-compatibiliy 标志并开始使用新的响应格式。

    ¥Disable the retro-compatibiliy flag by removing the Strapi-Response-Format: v4 header and start using the new response format.

迁移 GraphQL API 调用​

¥Migrate GraphQL API calls

  1. 通过在 /config/plugins.js|ts 文件 的 graphl.config 对象中将 v4CompatibilityMode 设置为 true 来启用追溯兼容性标志。

    ¥Enable the retro-compatibility flag by setting v4CompatibilityMode to true in the graphl.config object of the /config/plugins.js|ts file.

  2. 仅在专用 GraphQL 的重大变更条目 的指导下更新你的查询和修改。

    ¥Update your queries and mutations only, guided by the dedicated breaking change entry for GraphQL.

  3. 验证你的客户端是否正常运行。

    ¥Validate that your client is running correctly.

  4. 通过将 v4CompatibilityMode 设置为 false 禁用 retro-compatibily 标志并开始使用新的响应格式。

    ¥Disable the retro-compatibily flag by setting v4CompatibilityMode to false and start using the new response format.