Skip to main content

升级到 Strapi 5：简介和常见问题

¥Upgrading to Strapi 5: Introduction and FAQ

Strapi 的最新主要版本是 Strapi 5。Strapi v4 的支持将持续到 2026 年 4 月。

¥The latest major version of Strapi is Strapi 5. Strapi v4 is still supported until April 2026.

每当你准备好升级到 Strapi 5 时，当前页面都会为你提供帮助。它列出了从 Strapi 4 升级到 Strapi 5 的所有可用资源，并回答你可能遇到的一般问题。

¥Whenever you feel ready to upgrade to Strapi 5, the present page will help you. It lists all available resources for upgrading from Strapi 4 to Strapi 5 and answers general questions you might have.

可用资源​

¥Available resources

以下所有可用资源将帮助你将应用和插件升级到 Strapi 5，从最常见到最具体的用例：

¥All of the following available resources will help you upgrade your application and plugins to Strapi 5, from the most common to the most specific use cases:

常见问题​

¥Frequently asked questions

以下问题及其答案应可帮助你涵盖最常见的用例：

¥The following questions and their answers should help you cover the most common use cases:

How can I handle the upgrade and the installation of the latest dependencies?
How can I handle the breaking changes in the code and adapt my code to Strapi 5?

Strapi 提供了 升级工具 来简化该过程。升级工具是一个命令行工具，带有一些命令，用于处理依赖的升级和 codemods 的执行。

¥Strapi provides an upgrade tool to ease the process. The upgrade tool is a command line tool with some commands that handle the upgrade of the dependencies and the execution of codemods .

按照 分步指南 了解如何在升级到 Strapi 5 的背景下使用此工具。

¥Follow the step-by-step guide to learn how to use this tool in the context of upgrading to Strapi 5.

Strapi 5 文档还提供了 完整的重大更改数据库 和 专用资源 来涵盖特定用例。

¥Strapi 5 docs also provide a complete breaking changes database and dedicated resources to cover specific use cases.

How can I handle the data migration, ensuring that in Strapi 5 the application will still be working?

Strapi 5 integrates a series of data migration scripts that are run once the application starts for the first time in Strapi 5.

However, please always backup your database (found at .tmp/data.db by default if using a SQL database) before performing any upgrade, as instructed in the step-by-step guide.


As a Strapi Cloud customer, how can I handle the entire upgrade and deployment of my Strapi 5 application?

  1. 创建备份 并按照 分步指南 在本地更新你的代码。

    ¥Create a backup and update your code locally, following the step-by-step guide.

  2. 从 Cloud CLI 运行 yarn deploy 或 npm run deploy 命令。

    ¥Run the yarn deploy or npm run deploy commands from the Cloud CLI.

Strapi Cloud 将在 Strapi 5 中部署更新的代码，并自动运行数据迁移脚本。

¥Strapi Cloud will deploy the updated code in Strapi 5 and will automatically run the data migration script.

How do I keep the legacy attributes wrapper during the migration?

  • 对于 REST 客户端，请在重构代码时添加 Strapi-Response-Format: v4 标头。新的响应格式（重大变更） 指示在 curl、fetch 和 Axios 请求中添加标头的位置。

    ¥For REST clients, add the Strapi-Response-Format: v4 header while you refactor your code. The new response format breaking change shows where to add the header in curl, fetch, and Axios requests.

  • 对于 GraphQL 客户端，请启用 v4CompatibilityMode 并按照 GraphQL API 迁移文档 的步骤逐步移除 attributes。

    ¥For GraphQL clients, enable v4CompatibilityMode and follow the steps of the GraphQL API migration documentation to gradually remove attributes.

  • 启用标头后，REST 响应将继续同时公开 id（旧版）和 documentId。GraphQL 永远不会公开数字 id，因此即使在关闭兼容模式之前，也请将查询更新为使用 documentId。

    ¥REST responses continue to expose both id (legacy) and documentId when the header is enabled. GraphQL never exposes numeric id, so update your queries to use documentId even before you turn compatibility mode off.

一旦所有使用者都读取扁平化格式，就移除标头，以便 Strapi 默认发出 Strapi 5 响应格式。

¥Once every consumer reads the flattened format, remove the header so Strapi emits the Strapi 5 response shape by default.