Skip to main content

升级到 Strapi 5：介绍与常见问题

🌐 Upgrading to Strapi 5: Introduction and FAQ

Page summary:

从 v4 升级到 Strapi 5 使用带有 codemods 的升级工具来处理代码更改，而内置的数据迁移脚本会在首次启动时自动更新数据库。

🌐 Upgrading to Strapi 5 from v4 uses an upgrade tool with codemods to handle code changes, while built-in data migration scripts automatically update the database on first startup.

Strapi 的最新主要版本是 Strapi 5。Strapi v4 已于 2026 年 4 月 30 日停止维护。4.26.2 版本（2026 年 6 月 9 日）是 v4 的最后一个版本，以后不会再发布 v4 的更新。Strapi Cloud 仍然可以运行现有的 v4 项目，但将来可能会在没有警告的情况下发生变化。

🌐 The latest major version of Strapi is Strapi 5. Strapi v4 reached end of life on April 30, 2026. Release 4.26.2 (June 9, 2026) is the final v4 release, and no further v4 updates are published. Strapi Cloud can still run existing v4 projects, but that may change in the future without warning.

每当你准备好升级到 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:

我该如何处理升级以及最新依赖的安装？
我该如何处理代码中的重大更改并将我的代码适配到 Strapi 5？

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

Codemods are automated tools used for large-scale code modifications, especially useful for refactoring, adapting to API changes, or applying coding style updates. They enable precise and programmable alterations to source code.

的命令。

按照 逐步指南 学习如何在升级到 Strapi 5 的情况下使用此工具。

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


我如何处理数据迁移，以确保在 Strapi 5 中应用仍然能够正常工作？

Strapi 5 集成了一系列数据迁移脚本，这些脚本会在应用首次启动 Strapi 5 时运行。

但是，请 务必备份你的数据库 （如果使用 SQL 数据库，默认位置为 .tmp/data.db）在执行任何升级之前，如 逐步指南中所述。


作为 Strapi Cloud 的客户，我如何处理整个 Strapi 5 应用的升级和部署？
  1. 创建备份 并在本地更新你的代码，按照 逐步指南操作。
  2. 从 Cloud CLI 运行 yarn deploy 或 npm run deploy 命令。

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


在迁移过程中，我如何保持遗留的 attributes 封装器？
  • 对于 REST 客户端，在重构代码时添加 Strapi-Response-Format: v4 头。新的响应格式破坏性更改 (new response format breaking change) 显示了在 curl、fetch 和 Axios 请求中添加该头的位置。
  • 对于 GraphQL 客户端，启用 v4CompatibilityMode 并按照 GraphQL API 迁移文档 的步骤逐步移除 attributes。
  • 当启用该头时，REST 响应仍会同时暴露 id（旧版）和 documentId。GraphQL 从不暴露数字 id，因此即使在关闭兼容模式之前，也请更新你的查询以使用 documentId。

一旦每个消费者读取了扁平化格式，移除头部，这样 Strapi 就会默认发出 Strapi 5 响应格式。


为什么在我的项目仍然使用 Strapi v4 时，管理界面构建会出现 Cannot find module 'react' 错误？

在 Strapi v4 的小版本中进行补丁升级时，可能会导致管理面板构建失败，并出现 Cannot find module 'react'（或类似错误）。较新的 v4 系列版本期望在你的应用 package.json 中显式列出 react、react-dom、react-router-dom 和 styled-components，而不仅仅依赖传递依赖的解析。

从与目标版本匹配的新 Strapi v4 项目复制版本（例如在一个临时文件夹中运行官方生成器），然后安装并重建。一个典型的集合如下：

"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-router-dom": "5.3.4",
"styled-components": "5.3.3"

在 @strapi/strapi 上使用波浪号或插入符号范围（例如 ~4.25.22）用于补丁更新是可以的；当你跨过几个小版本时，请阅读每次跳跃的发布说明和迁移说明。

归档的 v4 开发者文档仍然存在 docs-v4.strapi.io。


我可以从 Strapi 5 降级回 Strapi 4 吗？

Strapi 不提供从 Strapi 5 自动降级到 Strapi 4 的功能。

Strapi 5 启动时运行的数据迁移脚本不会被产品自动回滚。

如果你必须返回到 Strapi 4，请恢复在升级前创建的数据库备份。查看仍然与 Strapi 4 匹配的 Git 分支或标签。

重新安装依赖，以便 package.json 和锁文件与该快照匹配。

在升级生产环境之前，使用 分步骤指南 规划备份和预演环境。


On this page