Skip to main content

逐步升级到 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. 备份你的数据库：
    • 如果你使用 SQLite 且采用默认配置（Strapi 提供的默认数据库），你的数据库文件名为 data.db，并位于 Strapi 应用根目录下的 .tmp/ 文件夹中。
    • 如果你使用的是其他类型的数据库，请参阅其官方文档（见 PostgreSQL docs 和 MySQL docs）。
    • 如果你的项目托管在 Strapi Cloud 上，你可以手动创建备份。
  2. 备份你的代码：
    • 如果你的代码已使用 git 进行版本控制，请创建一个新的专用分支来运行迁移。
    • 如果你的代码没有使用 git 进行版本控制，请创建你正在使用的 Strapi v4 代码的备份，并将其存放在安全的地方。
  3. 确保你使用的插件与 Strapi 5 兼容。

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

步骤 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. 运行升级工具。
npx @strapi/upgrade major

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

codemods 将处理以下更改：

Codemod name and GitHub code linkDescription
comment-out-lifecycle-filesComment out lifecycles files in favor of Document Service Middlewares
dependency-remove-strapi-plugin-i18nRemove the i18n plugin dependency as i18n is now integrated into the core of Strapi
dependency-upgrade-react-and-react-domUpgrade the react and react-dom dependencies
dependency-upgrade-react-router-domUpgrade the react-router-dom dependency
dependency-upgrade-styled-componentsUpgrade the styled-components dependency
deprecate-helper-pluginPartly handle migrations from @strapi/helper-plugin
entity-service-document-servicePartly handle the migration from the Entity Service API to the new Document Service API
s3-keys-wrapped-in-credentialsWrap the accessKeyId and secretAccessKey properties inside a credentials object for users using the aws-s3 provider
sqlite3-to-better-sqlite3Update the sqlite dependency to better-sqlite3
strapi-public-interfaceTransform @strapi/strapi imports to use the new public interface
use-uid-for-config-namespaceReplace string dot format for config get/set/has with uid format for 'plugin' and 'api' namespace where possible
utils-public-interfaceUpdate utils to use the new public interface
Tip

如果你开发 Strapi 插件，其他代码修改工具会处理 helper-plugin 弃用的一些方面。有关更多信息，请参见相关的重大更改。

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

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

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

Document Service API

关于文档服务 API 的更多信息可以在重大更改条目说明、特定迁移指南和API 参考中找到。

步骤 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. 数据库迁移：
    1. 不支持 MySQL v5 👉 查看 重大变更
    2. 仅支持 better-sqlite3 👉 参见 breaking change
    3. 只支持 mysql2 👉 参见 重大更改
    4. 生命周期钩子的触发方式有所不同 👉 请参见 重大更改
  2. 配置：
    1. 一些环境变量由服务器配置处理 👉 参见 重大更改
    2. 自定义配置必须满足特定要求 👉 请参见 重大更改
  3. 管理面板自定义：

👉 最后，查看剩余的 breaking changes 数据库，以了解你可能关心的任何边缘情况。

步骤 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. 通过在 HTTP 客户端、SDK 和中间件的 REST 调用中添加 Strapi-Response-Format: v4，在所有仍然期望使用 attributes 的地方启用兼容性头（具体示例请参见重大更改条目）。
  2. 在启用头部的同时，审计现有的有效负载。捕获有代表性的响应（包括已填充的关系、组件和媒体），以便在过渡期间验证旧版使用者仍能正常工作。
  3. 通过以下方式更新和测试每个客户端：
    • 移除 data.attributes 访问权限，
    • 切换到扁平化有效负载后，
    • 并在以前 REST API 仅返回数字 id 的地方采用 documentId。
  4. 针对每个端点或消费者禁用兼容性头：一旦某个客户端的测试通过，从其请求中移除 Strapi-Response-Format: v4。重复此操作，直到没有消费者依赖旧封装器。

迁移 GraphQL API 调用​

🌐 Migrate GraphQL API calls

  1. 通过在 graphql 插件配置中将 v4CompatibilityMode 设置为 true 来启用兼容性头，以便客户端在你重构它们时可以继续依赖 data.attributes。
  2. 按照 GraphQL 的重大变更条目 的每一步操作。这将指导你用 documentId 替换 id，采用 _connection 查询，移除 attributes，并最终切换到 nodes/pageInfo。
  3. 通过确认在为不需要 Relay 语义的客户端移除 _connection 和 data 时分页元数据仍然符合预期，测试 Relay 和非 Relay 查询。
  4. 禁用 v4CompatibilityMode 兼容性头：在每个查询和变更都能使用扁平化模式后，将头设置为 false，以便服务器默认输出 Strapi 5 格式。