ContextQMD
Back to Nocobase

编写第一个 NocoBase 插件

docs/docs/cn/plugin-development/write-your-first-plugin.md

2.1.27.4 KB
Original Source

编写第一个插件

这篇文档会带你从零创建一个可在页面中使用的区块插件，帮你了解 NocoBase 插件的基本结构和开发流程。

前置条件

开始之前，确保你已经安装好了 NocoBase。如果还没有安装，可以参考：

安装完成后就可以开始了。

第 1 步：通过 CLI 创建插件骨架

在仓库根目录执行以下命令，快速生成一个空的插件：

bash
yarn pm create @my-project/plugin-hello

命令执行成功后，会在 packages/plugins/@my-project/plugin-hello 目录下生成基础文件，默认结构如下：

bash
├─ /packages/plugins/@my-project/plugin-hello
  ├─ package.json
  ├─ README.md
  ├─ client-v2.d.ts
  ├─ client-v2.js
  ├─ server.d.ts
  ├─ server.js
  └─ src
     ├─ index.ts                 # 默认导出服务端插件
     ├─ client-v2                 # 客户端代码存放位置
     │  ├─ index.tsx             # 默认导出的客户端插件类
     │  ├─ plugin.tsx            # 插件入口（继承 @nocobase/client-v2 Plugin）
     │  ├─ models                # 可选：前端模型（如流程节点）
     │  │  └─ index.ts
     │  └─ utils
     │     ├─ index.ts
     │     └─ useT.ts
     ├─ server                   # 服务端代码存放位置
     │  ├─ index.ts              # 默认导出的服务端插件类
     │  ├─ plugin.ts             # 插件入口（继承 @nocobase/server Plugin）
     │  ├─ collections           # 可选：服务端 collections
     │  ├─ migrations            # 可选：数据迁移
     │  └─ utils
     │     └─ index.ts
     ├─ utils
     │  ├─ index.ts
     │  └─ tExpr.ts
     └─ locale                   # 可选：多语言
        ├─ en-US.json
        └─ zh-CN.json

创建完成后，你可以在浏览器中访问「插件管理器」页面（默认地址：http://localhost:13000/admin/settings/plugin-manager），确认插件是否已出现在列表中。

第 2 步：实现一个简单的客户端区块

接下来给插件添加一个自定义区块模型，展示一段欢迎文本。

  1. 新增区块模型文件 client-v2/models/HelloBlockModel.tsx：
tsx
import { BlockModel } from '@nocobase/client-v2';
import React from 'react';
import { tExpr } from '../utils';

export class HelloBlockModel extends BlockModel {
  renderComponent() {
    return (
      <div>
        <h1>Hello, NocoBase!</h1>
        <p>This is a simple block rendered by HelloBlockModel.</p>
      </div>
    );
  }
}

HelloBlockModel.define({
  label: tExpr('Hello block'),
});
  1. 注册区块模型。编辑 client-v2/models/index.ts，把新模型导出，供前端运行时加载：
ts
import { ModelConstructor } from '@nocobase/flow-engine';
import { HelloBlockModel } from './HelloBlockModel';

export default {
  HelloBlockModel,
} as Record<string, ModelConstructor>;

保存代码后，如果你正在运行开发脚本，应该能在终端输出中看到热更新的日志。

第 3 步：激活并体验插件

你可以通过命令行或界面开启插件：

  • 命令行

    bash
    yarn pm enable @my-project/plugin-hello

  • 管理界面：访问「插件管理器」，找到 @my-project/plugin-hello，点击「激活」。

激活后，新建一个「Modern page (v2)」页面，添加区块时就能看到「Hello block」，把它插入页面就能看到你刚才写的欢迎内容。

让插件默认预置或默认启用（可选）

上面讲的是手动开启单个插件。如果你在维护自己的 NocoBase 应用，希望某些插件在执行 nocobase install（首次安装）或 nocobase upgrade（升级）后就自动准备好，可以用两个环境变量来控制插件的默认状态：

  • APPEND_PRESET_LOCAL_PLUGINS（追加默认预置插件） — 把插件加入预置的本地插件列表，安装后出现在「插件管理器」里，但默认不激活，需要你手动开启
  • APPEND_PRESET_BUILT_IN_PLUGINS（追加默认内置插件） — 把插件加入内置插件列表，安装时自动激活，而且作为内置插件，在「插件管理器」里不能被停用或删除

两个变量的值都是插件包名（package.json 里的 name），多个插件用英文逗号分隔。在 .env 里这样配置：

bash
# 默认预置：出现在插件管理器列表，但不自动激活
APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world

# 默认启用：自动安装并激活，且不能在界面停用
APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world

通常来说，本地开发调试用前面的 yarn pm enable 就够了。这两个变量更适合「开箱即用」的发行场景——比如你打包了一套带固定插件的 NocoBase 应用，想让插件在初始化后直接可用。

:::tip 提示

  • 插件要已经下载到本地、能在 node_modules 里被解析到，参考项目目录结构
  • 配置后需要重新执行 nocobase install 或 nocobase upgrade 才会生效
  • 完整的环境变量说明见环境变量

:::

第 4 步：构建与打包

当你准备把插件分发到其他环境时，需要先构建再打包：

bash
yarn build @my-project/plugin-hello --tar
# 或者分两步执行
yarn build @my-project/plugin-hello
yarn nocobase tar @my-project/plugin-hello

:::tip 提示

如果插件是在源码仓库中创建的，首次构建会触发整仓库的类型检查，耗时可能较长。建议确保依赖已安装，并保持仓库处于可构建状态。

:::

构建完成后，打包文件默认位于 storage/tar/@my-project/plugin-hello.tar.gz。

:::tip 提示

插件发布前建议编写测试用例验证核心逻辑，NocoBase 提供了完整的服务端测试工具链。详见 Test 测试。

:::

第 5 步：上传到其他 NocoBase 应用

把打包文件上传并解压到目标应用的 ./storage/plugins 目录。详细步骤见 安装与升级插件。

相关链接