环境准备与开发模式

本文说明 BPMAX 插件开发所需的基础条件和本地开发方式，目标是先把开发环境跑起来。

学习目标

  • 理解插件开发需要准备哪些工具和配置
  • 能在本地完成插件开发环境准备
  • 知道开发时哪些操作需要重启，哪些只需刷新

开发对象

插件工程

  • 插件源码所在工程
  • 新插件开发从这里开始

本地开发环境

  • 平台运行环境通过 Docker 启动
  • 插件通过编译和同步机制注入本地运行环境

推荐的本地开发流程如下：

  1. 在插件工程中编写插件代码
  2. 用 docker-compose 启动本地开发容器
  3. 用 yarn dev-build-plugin 自动编译并注入运行环境

一个常见的本地开发目录关系如下：

workspace/
├── my_plugin/
│   ├── config.json
│   ├── frontend/
│   └── server/
├── docker-compose.yml
└── .env.docker

开发前准备

Node 与包管理器

当前文档工程要求 Node.js v22.0.0+，包管理器使用 pnpm 10.9.0+。插件开发时建议优先遵循当前插件工程已有的包管理约定。

Docker 环境

如果使用本地 Docker 开发环境，还需要准备：

  • Docker Desktop
  • 能访问镜像仓库的 Docker 环境

开发配置

在这套 Docker 本地开发环境中，日常开发通常采用以下方式：

  • 通过 docker-compose up 启动本地运行环境
  • 通过 yarn dev-build-plugin 启动插件 watch 和编译

选择要开发的插件

开发环境的关键开关在 .env.docker 中。需要把：

PLUGIN_NAME=替换成要开发的插件名

改成当前要开发的插件，例如：

PLUGIN_NAME=audio_upload

一个更完整的示例可以写成：

PLUGIN_NAME=plugin_hello_demo
APP_PORT=18080
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

准备环境变量

不同插件常常依赖不同环境变量，例如：

  • 第三方平台 app_id、secret
  • OSS 配置
  • Kafka 配置
  • 其他外部服务地址

如果只是做最小插件，这一步可以先简化；如果是集成类插件，建议一开始就把依赖配置补齐。

基于 Docker 的本地开发环境

第一次启动

  1. 安装 Docker Desktop
  2. 完成镜像仓库登录
  3. 复制配置模板
  4. 修改 .env.docker
  5. 启动容器
  6. 启动插件编译 watch

镜像仓库登录命令以本地开发环境提供的说明为准，确保当前 Docker 环境已经具备镜像拉取权限。

复制模板文件：

  • docker-compose.yml.template -> docker-compose.yml
  • .env.docker.template -> .env.docker

Windows 下还需要把 .env.docker 的换行符改成 LF。

如果 docker-compose.yml 需要指定本地插件工程，结构通常类似：

services:
  app:
    image: your-local-runtime-image
    env_file:
      - .env.docker
    ports:
      - "18080:18080"

启动环境

先启动本地运行环境：

docker-compose up

再新开一个终端，启动插件开发编译：

yarn dev-build-plugin

如果当前工程支持 watch 编译，启动后的终端输出通常会连续看到：

[watch] frontend build success
[watch] server build success
[watch] sync files completed

启动完成后，默认从：

  • localhost:18080

访问本地环境。

切换开发插件

切换插件时，核心就是修改 .env.docker 中的 PLUGIN_NAME，然后重新执行开发流程。

升级环境版本

如果要升级本地运行环境版本，直接修改 docker-compose.yml 中镜像版本，再重启 docker-compose 即可。

切换依赖环境

如果要切换数据库、Redis、Elasticsearch 等依赖环境，可以修改 .env.docker 中对应配置，再重启 docker-compose。

本地开发流程

第一步：创建或指定插件

如果是开发新插件，先通过脚手架复制一个已有插件：

node create_plugin.js --name=my_plugin --from=template_plugin

如果是继续开发已有插件，则直接进入对应插件目录即可。

如果只是想验证开发链路，推荐先准备这样一个最小工程：

plugin_hello_demo/
├── config.json
├── frontend/
│   └── src/
│       ├── main.ts
│       └── HelloPage.vue
└── server/
    └── src/
        └── controller/

第二步：安装插件自身依赖

在 Docker 开发模式下，这一步经常由开发脚本间接完成。但如果插件首次拉起失败，仍建议检查插件目录中的：

  • frontend/package.json
  • server/package.json

并根据工程约定补装依赖。

补充：migrations/ 怎么写

如果插件需要新增表、补字段或修历史数据，迁移脚本应在插件 server/ 工程中维护。

一个常见的后端目录结构如下：

server/
├── migrations/
│   └── .gitkeep
├── config/
├── src/
└── package.json

先在 server/package.json 中定义迁移命令

迁移文件不要靠手工创建，建议统一通过插件 server/package.json 中的命令生成和执行。

一个常见写法如下：

{
  "scripts": {
    "migrate:create": "db-migrate create --sql-file",
    "migrate": "db-migrate -e mysql",
    "migrate-dev": "db-migrate -e mysql"
  }
}

推荐至少保留三类命令：

  • migrate:create：创建迁移模板
  • migrate：执行默认环境迁移
  • migrate-dev：执行开发环境迁移

使用命令创建迁移

定义好脚本后，在插件 server/ 目录下执行：

yarn migrate:create create-task-map

如果当前工程使用 SQL 文件模式，可以写成：

yarn migrate:create create-task-map --sql-file

执行后通常会生成：

server/
└── migrations/
    ├── 202603180001-create-task-map.js
    └── sqls/
        ├── 202603180001-create-task-map-up.sql
        └── 202603180001-create-task-map-down.sql

这样做的好处是：

  • 时间戳和文件名格式统一
  • up / down 文件成对生成
  • 团队协作时不容易出现命名不一致

什么时候用 SQL 文件，什么时候写 JS

  • 表结构变更为主时，优先使用 --sql-file
  • 需要复杂数据修复、条件判断或批量计算时，可以使用 JS 迁移文件

如果项目已经采用 db-migrate 的 SQL 文件模式，建议保持一致，不要一部分脚本用 SQL，一部分脚本再改成完全不同的手工格式。

迁移示例

如果使用 JS 迁移文件，新增一个任务绑定表可以写成：

export default class {
  async up(db) {
    await db.query(`
      CREATE TABLE IF NOT EXISTS plugin_task_map (
        id BIGINT PRIMARY KEY AUTO_INCREMENT,
        project_guid VARCHAR(64) NOT NULL,
        step_guid VARCHAR(64) NOT NULL,
        external_task_id VARCHAR(128) NOT NULL,
        status VARCHAR(32) NOT NULL DEFAULT 'pending',
        created_at BIGINT NOT NULL,
        updated_at BIGINT NOT NULL
      )
    `);
  }

  async down(db) {
    await db.query(`DROP TABLE IF EXISTS plugin_task_map`);
  }
}

如果使用 SQL 文件模式，对应的 up.sql 可以写成：

CREATE TABLE plugin_task_map (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  project_guid VARCHAR(64) NOT NULL,
  step_guid VARCHAR(64) NOT NULL,
  external_task_id VARCHAR(128) NOT NULL,
  status VARCHAR(32) NOT NULL DEFAULT 'pending',
  created_at BIGINT NOT NULL,
  updated_at BIGINT NOT NULL
);

对应的 down.sql 可以写成：

DROP TABLE IF EXISTS plugin_task_map;

开发阶段如何执行迁移

在插件 server/ 目录下，通常这样执行：

yarn migrate-dev

如果使用默认环境：

yarn migrate

迁移完成后，再继续验证接口、模型和安装升级链路。

第三步：启动本地运行环境

建议直接启动 Docker 开发环境：

docker-compose up

插件不是独立站点，它运行在平台环境中。

第四步：验证插件是否被加载

建议按下面顺序验证：

  1. 前端页面或插槽是否出现
  2. 浏览器控制台是否有插件日志
  3. 服务日志中是否有插件相关日志
  4. 对应接口是否可以访问
  5. yarn dev-build-plugin 是否持续输出编译日志

热更新与重启边界

前端改动

在 Docker 开发模式下，前端改动通常会先经过插件自己的构建流程，再由本地运行环境读取构建产物。很多情况下刷新页面即可看到效果，但前提是 yarn dev-build-plugin 正在正常运行。

例如下面这类改动通常只需要刷新页面：

<template>
  <section>
    <h2>Plugin Dashboard</h2>
  </section>
</template>

后端改动

开发脚本会监听插件后端源码变化，编译后再把结果同步到本地运行环境。

这意味着后端并不是直接读源码，而是读编译后的结果。关键改动后仍建议检查：

  • 编译是否成功
  • 文件是否成功同步到运行环境
  • 本地运行环境是否已重载生效

例如下面这类控制器改动，通常需要确认编译和同步日志已经完成：

async pingAction() {
  return this.success({
    message: 'pong',
    timestamp: Date.now(),
  });
}

安装脚本或迁移改动

这类改动不建议只靠热更新验证，通常要重新走一次安装或升级流程。

定时任务改动

定时任务不仅依赖代码生效，还依赖调度配置，因此改动后建议同时验证：

  • 配置文件是否生效
  • enable 条件是否满足
  • handle 路径是否可访问

常见开发目录

插件前端目录

一般是：

{plugin}/frontend

插件后端目录

一般是：

{plugin}/server

开发环境相关文件

如果使用 Docker 开发模式，除了插件源码目录，还要重点关注：

docker-compose.yml
.env.docker

因为它们决定了：

  • 当前加载的是哪个插件
  • 本地运行环境怎么启动

常见问题

插件页面没有出现

  • 路由没有注册
  • 插件前端入口没有被加载
  • 页面路径与访问路径不一致
  • yarn dev-build-plugin 没有运行
  • PLUGIN_NAME 配置错了

后端接口未生效

  • 接口文件未被运行环境正确识别
  • 后端没有成功编译并同步到容器
  • 接口路径写错

安装后仍需重启

这是正常情况。插件安装或更新后，平台通常还需要通过重载机制使结果生效，因此不应把安装行为理解为纯前端热更新。

下一步