插件升级摘要

¥Plugins upgrade summary

本页面旨在简要概述如果你是插件开发者，需要将插件从 Strapi v4 升级到 Strapi 5 时需要考虑的所有事项。该页面快速描述了影响插件的更改，并在必要时链接到其他资源。

¥The present page is intended to be used as a short summary of everything to consider if you are a plugin developer upgrading your plugin from Strapi v4 to Strapi 5. The page quickly describes the changes affecting plugins and links to additional resources where necessary.

🤓 插件 SDK

从 Strapi 5 开始，该平台包含一个 插件 SDK 来帮助开发和构建 Strapi 插件。虽然你可以自由使用其他方法进行插件开发，但我们强烈建议你使用插件 SDK。作为从 v4 到 Strapi 5 的迁移过程的一部分，我们鼓励你更新插件以利用插件 SDK。

¥Starting with Strapi 5, the platform includes a Plugin SDK to help develop and build Strapi plugins. While you are free to use other methods for plugin development, we strongly recommend using the Plugin SDK. As part of the migration process from v4 to Strapi 5, we encourage you to update your plugin to take advantage of the Plugin SDK.

建议步骤迁移插件

¥Recommended steps to migrate a plugin

☑️ Prerequisites

你的 Strapi 应用已在最新的 v5 次要版本和补丁版本上运行。如果不是，请按照 分步指南 升级到 Strapi 5。

¥Your Strapi application is already running on the latest v5 minor and patch version. If it's not, follow the step-by-step guide to upgrade to Strapi 5.

将 Strapi v4 插件升级到 Strapi 5 包括：

¥Upgrading a Strapi v4 plugin to Strapi 5 consists in:

1. 使用 插件 SDK 创建一个新的空插件。

   ¥Creating a new empty plugin using the Plugin SDK.

2. 将你的 Strapi v4 代码移动到 Strapi 5 插件结构 中新创建的文件中，同时考虑本页中总结的更改。

   ¥Move your Strapi v4 code to the newly created files in the Strapi 5 plugin structure, also considering the changes summarized in this page.

💡 提示：部分自动化迁移

插件迁移的某些部分可以通过 CLI 升级工具通过其 codemods 自动补齐。你可以运行 npx @strapi/upgrade codemods ls 以列出可用的 codemod，并运行 npx @strapi/upgrade codemods run 以运行特定的 codemod。有关更多详细信息，请参阅 codemods 列表 和 升级工具的参考文档。

¥Some parts of the plugin migration can be automated by the CLI upgrade tool through its codemods . You can run npx @strapi/upgrade codemods ls to list available codemods and npx @strapi/upgrade codemods run to run a specific codemod. See the list of codemods and the reference documentation for the upgrade tool for more details.

或者，你可以手动更新你的 Strapi v4 插件以使用插件 SDK。手动步骤包括：

¥Alternatively, you can manually update your Strapi v4 plugin to use the Plugin SDK. The manual steps include:

1. 如果你的代码使用 CommonJS 以外的格式，请更新 package.json 文件并指定适当的导出属性。

   ¥If your code uses a format other than CommonJS, update the package.json file and specify the appropriate exports property.

2. 将默认 插件结构 文件重命名为 。

   ¥Reorganize your Strapi v4 code to align with the Strapi 5 plugin structure

后端更改

¥Back-end changes

• Strapi v4 中的实体服务 API 已弃用，Strapi 5 改用 文档服务 API。迁移指南 可帮助你过渡到文档服务 API。

  ¥The Entity Service API from Strapi v4 is deprecated and Strapi 5 uses the Document Service API instead. A migration guide is available to help you transition to the Document Service API.

• 一般来说，Strapi v4 到 Strapi 5 重大变更 可能适用。

  ¥General Strapi v4 to Strapi 5 breaking changes might apply.

• 你可以使用新的 插件 SDK 生成插件并将它们发布在 NPM 上和/或将它们提交到市场。

  ¥You can use the new Plugin SDK to generate plugins and publish them on NPM and/or submit them to the Marketplace.

前端更改

¥Front-end changes

• 设计系统在 Strapi 5 中升级到 v2：

  ¥The Design System is upgraded to v2 in Strapi 5:

  • 👉 专用迁移指南是 可在设计系统文档中获取。

    ¥👉 A dedicated migration guide is available in the Design System documentation.

  • 除了 icons 之外，没有大的视觉变化。

    ¥There are no big visual changes, except for icons.

  • 一般来说，Strapi v4 到 Strapi 5 重大变更 可能适用。

    ¥General Strapi v4 to Strapi 5 breaking changes might apply.

• helper-plugin 已被删除。迁移参考 可帮助你从 helper-plugin 过渡。

  ¥The helper-plugin has been removed. A migration reference is available to help you transition away from the helper-plugin.

• Strapi 不再为依赖设置别名。所有面向客户端的代码预计要使用的 4 个依赖在项目级别声明（react、react-dom、styled-components 和 react-router-dom）。如果你没有声明你使用的依赖（例如 axios），则用户可能会遇到插件无法预料的问题。

  ¥Strapi does not alias dependencies any longer. The 4 dependencies that are expected to be used by all client facing code are declared at the project level (react, react-dom, styled-components, and react-router-dom). If you do not declare the dependencies that you use (e.g. axios), there is a likelihood users could face unforeseen issues with your plugin.

• 如果你使用的是 插件 SDK，则需要将前端文件转换为 .jsx 或 .tsx 格式。

  ¥If you're using the Plugin SDK, you will need to transition your front-end files to .jsx or .tsx format.

自定义提供程序

¥Custom providers

电子邮件和上传插件的自定义 providers 仅在使用实体服务 API 时才需要转换（请参阅 实体服务 API 到文档服务 API 的迁移指南）。

¥Custom providers for the Email and Upload plugins need conversion only if they were using the Entity Service API (please refer to the Entity Service API to Document Service API migration guide).