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.

使用本地插件的配置​

¥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 的情况下在 monorepo 环境中设置本地插件​

¥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

    ¥server entry point: strapi-server.js|ts

  • 管理员入口点：strapi-admin.js|ts

    ¥admin entry point: 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.

提示

有关如何在 monorepo 环境中构建本地插件的完整示例，请查看我们的 strapi/strapi 存储库中的示例设置。

¥For a complete example of how to structure your local plugin in a monorepo environment, please check out our example setup in the strapi/strapi repository.

Contribute to this page