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

> Source: https://strapi.nodejs.cn/cms/migration/v4-to-v5/introduction-and-faq

🌐 Upgrading to Strapi 5: Introduction and FAQ

从 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 月。

🌐 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}

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

- [逐步指南](/cms/migration/v4-to-v5/step-by-step): 请先阅读本指南，以了解升级流程的概况。
- [升级工具参考](/cms/upgrade-tool): 了解更多关于升级工具如何自动将 Strapi v4 应用的部分内容迁移到 Strapi 5 的信息。
- [重大更改列表](/cms/migration/v4-to-v5/breaking-changes): 阅读更多关于 Strapi v4 和 v5 之间的差异、由此产生的重大更改，以及如何手动或借助升级工具提供的 codemod 来处理这些更改的信息。
- [特定资源](/cms/migration/v4-to-v5/additional-resources/introduction): 处理特定用例，例如弃用实体服务 API 以支持新的文档服务 API、插件迁移以及弃用辅助插件。

## 常见问题 {#frequently-asked-questions}

🌐 Frequently asked questions

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

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

<details style={{backgroundColor: 'transparent', border: 'solid 1px #4945ff' }}>
<summary style={{fontSize: '18px'}}>我该如何处理升级以及最新依赖的安装？<br/>我该如何处理代码中的重大更改并将我的代码适配到 Strapi 5？</summary>

Strapi 提供了一个[升级工具](/cms/upgrade-tool)以简化此过程。该升级工具是一个命令行工具，带有一些处理依赖升级和执行 **codemods**  的命令。

按照 <a href="/cms/migration/v4-to-v5/step-by-step">逐步指南</a> 学习如何在升级到 Strapi 5 的情况下使用此工具。

Strapi 5 文档还提供了一个[完整的重大更改数据库](/cms/migration/v4-to-v5/breaking-changes)和[专用资源](/cms/migration/v4-to-v5/additional-resources/introduction)来覆盖特定的使用案例。
<br/>

</details>

<details style={{backgroundColor: 'transparent', border: 'solid 1px #4945ff' }}>
<summary style={{fontSize: '18px'}}>我如何处理数据迁移，以确保在 Strapi 5 中应用仍然能够正常工作？</summary>
<p>Strapi 5 集成了一系列数据迁移脚本，这些脚本会在应用首次启动 Strapi 5 时运行。</p>
<p>但是，请 <strong>务必备份你的数据库</strong> （如果使用 SQL 数据库，默认位置为  <code style={{color: 'rgb(73, 69, 255)', backgroundColor: 'rgb(240, 240, 255)'}}>.tmp/data.db</code>）在执行任何升级之前，如 <a href="/cms/migration/v4-to-v5/step-by-step">逐步指南</a>中所述。</p>
<br/>
</details>

<details style={{backgroundColor: 'transparent', border: 'solid 1px #4945ff' }}>
<summary style={{fontSize: '18px'}}>作为 Strapi Cloud 的客户，我如何处理整个 Strapi 5 应用的升级和部署？</summary>

1. [创建备份](/cloud/projects/settings#backups) 并在本地更新你的代码，按照 <a href="/cms/migration/v4-to-v5/step-by-step">逐步指南</a>操作。
2. 从 [Cloud CLI](/cloud/cli/cloud-cli) 运行 `yarn deploy` 或 `npm run deploy` 命令。<br/>

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

</details>

<details style={{backgroundColor: 'transparent', border: 'solid 1px #4945ff' }}>
<summary style={{fontSize: '18px'}}>在迁移过程中，我如何保持遗留的 <code>attributes</code> 封装器？</summary>

- 对于 REST 客户端，在重构代码时添加 `Strapi-Response-Format: v4` 头。新的响应格式破坏性更改 ([new response format breaking change](/cms/migration/v4-to-v5/breaking-changes/new-response-format#migration)) 显示了在 `curl`、`fetch` 和 Axios 请求中添加该头的位置。
- 对于 GraphQL 客户端，启用 `v4CompatibilityMode` 并按照 [GraphQL API 迁移文档](/cms/migration/v4-to-v5/breaking-changes/graphql-api-updated#migration) 的步骤逐步移除 `attributes`。
- 当启用该头时，REST 响应仍会同时暴露 `id`（旧版）和 [`documentId`](/cms/migration/v4-to-v5/breaking-changes/use-document-id)。GraphQL 从不暴露数字 `id`，因此即使在关闭兼容模式之前，也请更新你的查询以使用 `documentId`。

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

</details>

<details style={{backgroundColor: 'transparent', border: 'solid 1px #4945ff' }}>
<summary style={{fontSize: '18px'}}>为什么在我的项目仍然使用 Strapi v4 时，管理界面构建会出现 <code>Cannot find module 'react'</code> 错误？</summary>

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

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

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

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

<p>归档的 v4 开发者文档仍然存在 [docs-v4.strapi.io](https://docs-v4.strapi.io/dev-docs/migration-guides)。</p>
<br/>

</details>

<details style={{backgroundColor: 'transparent', border: 'solid 1px #4945ff' }}>
<summary style={{fontSize: '18px'}}>我可以从 Strapi 5 降级回 Strapi 4 吗？</summary>

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

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

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

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

<p>在升级生产环境之前，使用 <a href="/cms/migration/v4-to-v5/step-by-step">分步骤指南</a> 规划备份和预演环境。</p>
<br/>

</details>