Skip to main content

插件创建

¥Plugin creation

创建 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).

✏️ 注意

本指南假设你想要开发 Strapi 项目外部的插件。但是，如果你想在现有项目中开发插件，步骤基本上保持不变。如果你不是 使用单一存储库，步骤完全相同。

¥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 一起）。

¥yalc must be installed globally (with npm install -g yalc or 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 dlx @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:

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

在上面的例子中，我们在将插件 (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 build && yarn 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.

在 monorepo 环境中使用插件 SDK​

¥Working with the Plugin SDK in a monorepo environment

如果你使用 monorepo 环境来开发插件，则不需要使用 watch:link 命令，因为 monorepo 工作区设置将处理符号链接。你可以改用 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;
};
✋ 提醒

因为服务器会查看 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.