插件创建

页面摘要： Plugin SDK 无需 Strapi 项目即可生成插件，并通过 watch:link 和 yalc 将其链接到现有应用。本文档包含用于打包插件以发布到 npm 或 Marketplace 的构建与验证命令，以及有关 monorepo 和本地设置的信息。

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

Plugin SDK 是一组围绕插件开发而设计的命令，既可将插件用作本地插件，也可将其发布到 NPM 和/或提交到 Marketplace。

使用 Plugin SDK，你在创建插件之前无需先搭建一个 Strapi 项目。

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

Plugin SDK 入门

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

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

创建插件

要创建你的插件，请确保你位于希望创建插件所在的父目录中，并运行以下命令：

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）。

你将被引导完成一系列提示，以帮助你设置插件。如果你对所有选项都选择 “是”，最终结构将类似于默认的 插件结构。

将插件链接到你的项目

为了在开发过程中测试你的插件，推荐的做法是将其链接到一个 Strapi 项目。

使用 watch:link 命令将你的插件链接到项目。该命令会输出有关如何将插件链接到 Strapi 项目的说明。

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

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

由于此插件是通过 node_modules 安装的，你无需将其显式添加到你的 plugins 配置文件 中，因此运行 develop 命令 启动你的 Strapi 项目时，会自动拾取你的插件。

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

你现在可以随心所欲地开发你的插件了！如果你在进行服务端更改，则需要重启服务器以使更改生效。

构建插件以进行发布

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

Yarn

yarn build && yarn verify

NPM

npm run build && npm run verify

上述命令不仅会构建插件，还会验证输出有效且可以发布。之后你可以像发布任何其他包一样，将插件发布到 NPM。

yarn add @strapi/sdk-plugin@5

npm install @strapi/sdk-plugin@5

在 monorepo 环境中使用 Plugin SDK {#monorepo}

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

但是，如果你在编写管理面板代码，可以添加指向插件源代码的 alias，以便在管理面板的上下文中更方便地进行开发：

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

本地插件的配置

由于 Plugin SDK 主要设计用于非本地插件开发，本地插件的配置需要手动调整。

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

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

然而，这种设置有时会导致如下错误：

Error: 'X must be used within StrapiApp';

当你的插件尝试导入 Strapi 核心功能时（例如使用以下方式）经常会出现此错误：

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

要解决此问题，请从插件的 devDependency 中移除 @strapi/strapi。这可确保插件使用与主应用相同的 Strapi 核心模块实例，从而避免冲突及相关的错误。

在没有 Plugin SDK 的情况下于 monorepo 环境中设置本地插件

在 monorepo 中，你可以通过在插件文件夹的根目录创建 2 个入口点文件，在不使用 Plugin SDK 的情况下配置本地插件：

• 服务端入口点：strapi-server.js
• 管理面板入口点：strapi-admin.js

这两个文件需要你自己创建：它们不会被自动脚手架生成。使用 Plugin SDK 创建的插件在其根目录没有此类文件，因为 SDK 会在插件的 package.json 中声明 strapi-server 和 strapi-admin 子路径导出，指向 dist/ 中的构建文件。

服务端入口点

服务端入口点文件初始化你的插件的服务端功能。strapi-server.js 的预期结构如下：

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

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

管理面板入口点

管理面板入口点文件在 Strapi 管理面板中设置你的插件。strapi-admin.js 的预期结构如下：

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

该对象包含用于向管理应用注册插件、执行引导操作以及处理翻译的方法。有关更多详细信息，请参阅 管理面板 API 参考。