插件创建

🌐 Plugin creation

Page summary:

插件 SDK 可以在没有 Strapi 项目的情况下生成插件，并使用 watch:link 和 yalc 将它们链接到现有应用。在本指南中：构建和验证命令用于打包插件以发布到 npm 或市场，以及用于 monorepo 和本地设置的信息。

创建 Strapi 5 插件的方法有很多，但最快和推荐的方法是使用插件 SDK。

🌐 There are many ways to create a Strapi 5 plugin, but the fastest and recommended way is to use the Plugin SDK.

插件 SDK 是一组命令，用于开发插件以将其用作本地插件或将它们发布在 NPM 上和/或将它们提交到 Marketplace。

🌐 The Plugin SDK is a set of commands orientated around developing plugins to use them as local plugins or to publish them on NPM and/or submit them to the Marketplace.

使用插件 SDK，你无需在创建插件之前设置 Strapi 项目。

🌐 With the Plugin SDK, you do not need to set up a Strapi project before creating a plugin.

本指南涵盖了从零创建插件、将其链接到现有 Strapi 项目以及发布插件。如果你已经有现有插件，则可以改为对插件设置进行改造以使用插件 SDK 命令（请参阅 插件 SDK 参考 获取可用命令的完整列表）。

🌐 The present guide covers creating a plugin from scratch, linking it to an existing Strapi project, and publishing the plugin. If you already have an existing plugin, you can instead retrofit the plugin setup to utilise the Plugin SDK commands (please refer to the Plugin SDK reference for a full list of available commands).

Note

本指南假设你希望开发一个独立于你的 Strapi 项目的插件。然而，如果你想在现有项目中开发插件，步骤基本保持不变。如果你没有使用 monorepo，步骤完全相同。

🌐 This guide assumes you want to develop a plugin external to your Strapi project. However, the steps largely remain the same if you want to develop a plugin within your existing project. If you are not using a monorepo the steps are exactly the same.

Prerequisites

yalc 必须全局安装（使用 npm install -g yalc 或 yarn global add yalc）。

开始使用插件 SDK

🌐 Getting started with the Plugin SDK

插件 SDK 可帮助你创建插件、将其链接到现有 Strapi 项目并构建它以供发布。

🌐 The Plugin SDK helps you creating a plugin, linking it to an existing Strapi project, and building it for publishing.

命令及其参数的完整列表可在 插件 SDK 参考 中找到。本页面将指导如何使用主要命令。

🌐 The full list of commands and their parameters are available in the Plugin SDK reference. The present page will guide on using the main ones.

创建插件

🌐 Creating the plugin

要创建插件，请确保你位于要创建插件的父目录中，然后运行以下命令：

🌐 To create your plugin, ensure you are in the parent directory of where you want it to be created and run the following command:

Yarn

yarn dlx @strapi/sdk-plugin init my-strapi-plugin

NPM

npx @strapi/sdk-plugin init my-strapi-plugin

路径 my-strapi-plugin 可以替换为你想为插件命名的任何名称，包括它应该创建的位置的路径（例如，code/strapi-plugins/my-new-strapi-plugin）。

🌐 The path my-strapi-plugin can be replaced with whatever you want to call your plugin, including the path to where it should be created (e.g., code/strapi-plugins/my-new-strapi-plugin).

你将会通过一系列提示来帮助你设置插件。如果你对所有选项都选择了“是”，最终的结构将类似于默认的 插件结构。

🌐 You will be ran through a series of prompts to help you setup your plugin. If you selected yes to all options the final structure will be similar to the default plugin structure.

将插件链接到你的项目

🌐 Linking the plugin to your project

为了在开发过程中测试你的插件，建议的方法是将其链接到 Strapi 项目。

🌐 In order to test your plugin during its development, the recommended approach is to link it to a Strapi project.

将你的插件链接到项目是通过 watch:link 命令完成的。该命令将输出关于如何将你的插件链接到 Strapi 项目的说明。

🌐 Linking your plugin to a project is done with the watch:link command. The command will output explanations on how to link your plugin to a Strapi project.

在新的终端窗口中，运行以下命令：

🌐 In a new terminal window, run the following commands:

Yarn

cd /path/to/strapi/project
yarn dlx yalc add --link my-strapi-plugin && yarn install

NPM

cd /path/to/strapi/project
npx yalc add --link my-strapi-plugin && npm install

Note

在上面的示例中，当将插件链接到项目时，我们使用插件的名称（my-strapi-plugin）。这是包的名称，而不是文件夹的名称。

🌐 In the above examples we use the name of the plugin (my-strapi-plugin) when linking it to the project. This is the name of the package, not the name of the folder.

由于这个插件是通过 node_modules 安装的，你不需要显式地将它添加到你的 plugins 配置文件 中，因此运行 develop command 来启动你的 Strapi 项目时会自动识别你的插件。

🌐 Because this plugin is installed via node_modules you won't need to explicity add it to your plugins configuration file, so running the develop command to start your Strapi project will automatically pick up your plugin.

现在你的插件已链接到项目，运行 yarn develop 或 npm run develop 来启动 Strapi 应用。

🌐 Now that your plugin is linked to a project, run yarn develop or npm run develop to start the Strapi application.

你现在可以按照自己的方式开发插件了！如果你进行了服务器更改，你需要重启服务器以使更改生效。

🌐 You are now ready to develop your plugin how you see fit! If you are making server changes, you will need to restart your server for them to take effect.

构建用于发布的插件

🌐 Building the plugin for publishing

当你准备发布你的插件时，你需要先构建它。为此，请运行以下命令：

🌐 When you are ready to publish your plugin, you will need to build it. To do this, run the following command:

Yarn

yarn build && yarn verify

NPM

npm run build && npm run verify

上述命令不仅会构建插件，还会验证输出是否有效并准备好发布。然后，你可以像发布其他任何包一样，将你的插件发布到 NPM。

🌐 The above commands will not only build the plugin, but also verify that the output is valid and ready to be published. You can then publish your plugin to NPM as you would any other package.

Upgrading from SDK Plugin v5

如果你正在从 @strapi/sdk-plugin v5 升级到 v6：

🌐 If you're upgrading from @strapi/sdk-plugin v5 to v6:

• 从你的插件中删除任何 packup.config.ts 文件（它不再使用）。
• 依赖 package.json#exports 进行构建配置（它现在是自动派生的）。
• 如果你需要源映射，请在构建命令中添加 --sourcemap（它们现在默认是关闭的）。

不需要其他更改。

🌐 No other changes are required.

Using SDK Plugin v5 (legacy)

如果你需要继续使用带有 @strapi/pack-up 的先前构建系统，你可以固定到 5.x 版本：

🌐 If you need to continue using the previous build system with @strapi/pack-up, you can pin to version 5.x:

Yarn

yarn add @strapi/sdk-plugin@5

NPM

npm install @strapi/sdk-plugin@5

SDK 插件的 5.x 版本支持用于自定义构建配置的 packup.config.ts。然而，推荐使用 v6 以获得安全更新和简化的配置。

🌐 Version 5.x of the SDK plugin supports packup.config.ts for custom build configuration. However, v6 is recommended for security updates and simplified configuration.

在单体仓库环境中使用插件 SDK

🌐 Working with the Plugin SDK in a monorepo environment

如果你在单一代码库环境中开发插件，则不需要使用 watch:link 命令，因为单一代码库工作区设置会处理符号链接。你可以改用 watch 命令。

🌐 If you are working with a monorepo environment to develop your plugin, you don't need to use the watch:link command because the monorepo workspace setup will handle the symlink. You can use the watch command instead.

然而，如果你正在编写管理代码，你可能会添加一个针对你的插件源代码的 alias，以便在管理面板的环境中更容易使用：

🌐 However, if you are writing admin code, you might add an alias that targets the source code of your plugin to make it easier to work with within the context of the admin panel:

import path from 'node:path';

export default (config, webpack) => {
  config.resolve.alias = {
    ...config.resolve.alias,
    'my-strapi-plugin': path.resolve(
      __dirname,
      // We've assumed the plugin is local.
      '../plugins/my-strapi-plugin/admin/src'
    ),
  };

  return config;
};

Caution

因为服务器查看 server/src/index.ts|js 文件以导入你的插件代码，所以你必须使用 watch 命令，否则代码不会被转译，服务器将无法找到你的插件。

🌐 Because the server looks at the server/src/index.ts|js file to import your plugin code, you must use the watch command otherwise the code will not be transpiled and the server will not be able to find your plugin.

使用本地插件的配置

🌐 Configuration with a local plugin

由于插件 SDK 主要用于开发插件，而不是本地开发，因此需要手动调整本地插件的配置。

🌐 Since the Plugin SDK is primarily designed for developing plugins, not locally, the configuration needs to be adjusted manually for local plugins.

在本地开发你的插件时（使用 @strapi/sdk-plugin），你的插件配置文件如下例所示：

🌐 When developing your plugin locally (using @strapi/sdk-plugin), your plugins configuration file looks like in the following example:

/config/plugins.js|ts

myplugin: {
  enabled: true,
  resolve: `./src/plugins/local-plugin`,
},

但是，此设置有时会导致以下错误：

🌐 However, this setup can sometimes lead to errors such as the following:

Error: 'X must be used within StrapiApp';

此错误通常发生在你的插件尝试导入核心 Strapi 功能时，例如使用：

🌐 This error often occurs when your plugin attempts to import core Strapi functionality, for example using:

import { unstable_useContentManagerContext as useContentManagerContext } from '@strapi/strapi/admin';

要解决此问题，请从你的插件中将 @strapi/strapi 移除为开发依赖。这可以确保你的插件使用与主应用相同的 Strapi 核心模块实例，从而防止冲突及相关错误。

🌐 To resolve the issue, remove @strapi/strapi as a dev dependency from your plugin. This ensures that your plugin uses the same instance of Strapi's core modules as the main application, preventing conflicts and the associated errors.

在没有插件 SDK 的情况下，在多仓库环境中设置本地插件

🌐 Setting a local plugin in a monorepo environment without the Plugin SDK

在 monorepo 中，你可以通过在插件根目录添加 2 个入口点文件来配置本地插件，而无需使用插件 SDK：

🌐 In a monorepo, you can configure your local plugin without using the Plugin SDK by adding 2 entry point files at the root of your plugin:

• 服务器入口点：strapi-server.js|ts
• 管理员入口：strapi-admin.js|ts

服务器入口点

🌐 Server entry point

服务器入口文件初始化插件的服务器端功能。strapi-server.js（或其 TypeScript 版本）的预期结构是：

🌐 The server entry point file initializes your plugin's server-side functionalities. The expected structure for strapi-server.js (or its TypeScript variant) is:

module.exports = () => {
  return {
    register,
    config,
    controllers,
    contentTypes,
    routes,
  };
};

在这里，你导出一个函数，该函数返回插件的核心组件，如控制器、路由和配置。有关更多详细信息，请参考服务器 API 参考。

🌐 Here, you export a function that returns your plugin's core components such as controllers, routes, and configuration. For more details, please refer to the Server API reference.

管理员入口

🌐 Admin entry point

管理员入口文件在 Strapi 管理面板中设置你的插件。strapi-admin.js（或其 TypeScript 变体）的预期结构是：

🌐 The admin entry point file sets up your plugin within the Strapi admin panel. The expected structure for strapi-admin.js (or its TypeScript variant) is:

export default {
  register(app) {},
  bootstrap() {},
  registerTrads({ locales }) {},
};

此对象包括用于向管理应用注册插件、执行引导操作以及处理翻译的方法。更多详情，请参阅 管理员面板 API 参考。

🌐 This object includes methods to register your plugin with the admin application, perform bootstrapping actions, and handle translations. For more details, please refer to the Admin Panel API reference.

Tip

有关如何在 monorepo 环境中构建本地插件的完整示例，请查看我们的 example setup in the strapi/strapi repository。