调试与排错

本文整理 BPMAX 插件开发和部署过程中最常见的问题及排查路径，帮助开发者快速定位问题。

学习目标

  • 理解插件调试的基本入口
  • 学会区分前端问题、后端问题、安装问题和运行时问题
  • 学会建立一条稳定的排查路径

调试入口

前端调试

优先确认：

  • 页面是否加载
  • 控制台是否有插件入口日志
  • 路由和插槽是否成功注册

推荐先保留最小入口日志：

console.log('[plugin_example] frontend loaded');

后端调试

优先确认：

  • 服务是否加载到运行环境
  • 接口是否能访问
  • 日志是否进入目标逻辑

后端入口可以先加：

async pingAction() {
  think.logger.info('[plugin_example] ping action');
  return this.success({ message: 'pong' });
}

开发模式调试

开发模式下，除了看页面和接口，还要确认：

  • docker-compose 是否正常运行
  • yarn dev-build-plugin 是否持续工作
  • 插件切换配置是否正确

已安装插件调试

已安装插件出现问题时，要区分是：

  • 打包产物问题
  • 安装流程问题
  • 运行时问题

常见问题分类

插件未加载

这类问题通常表现为：

  • 页面、插槽、接口都没有任何变化
  • 控制台和服务日志里没有插件入口日志
  • 修改代码后运行环境没有任何响应

优先检查：

  • PLUGIN_NAME 是否指向当前插件
  • docker-compose 是否正常运行
  • yarn dev-build-plugin 是否正在执行
  • 插件工程目录名与配置中的插件英文名是否一致

最先检查的两个配置片段通常是：

PLUGIN_NAME=plugin_hello_demo
{
  "en_name": "plugin_hello_demo"
}

前端页面未显示

这类问题通常表现为：

  • 路由访问 404 或空白页
  • 页面应该出现的位置没有显示任何内容
  • 控制台出现组件加载或运行时报错

优先检查：

  • 路由是否已注册
  • 插槽名是否正确
  • 页面组件是否成功参与构建
  • 前端构建产物是否已更新
  • 浏览器是否还在使用旧缓存

先确认入口里确实注册了路由：

BPMAX.router.addRoute({
  path: '/plugin/hello-demo',
  component: HelloPage,
});

接口未生效

这类问题通常表现为：

  • 请求返回 404
  • 请求到了平台但没有进入插件逻辑
  • 前端调用成功发出，但结果始终不符合预期

优先检查：

  • 接口路径是否正确
  • 控制器是否已参与编译
  • 后端编译结果是否已同步到运行环境
  • 请求参数是否满足接口进入条件
  • 服务层是否真的被控制器调用

例如先用一个最小接口验证链路：

async pingAction() {
  return this.success({
    plugin: 'plugin_example',
    message: 'pong',
  });
}

Hook 未触发

这类问题通常表现为：

  • 插件已加载，但挂接逻辑完全没有执行
  • 业务主流程正常运行，附加动作始终没有发生

优先检查：

  • Hook 事件名是否拼写正确
  • 插件是否在启动阶段完成了 Hook 注册
  • 当前操作是否真的会触发该事件
  • Hook 回调是否在前置判断中提前返回

先确认 Hook 是否真正注册：

think.addPluginHook('workflow.step.active', async function (context) {
  think.logger.info('[plugin_example] hook triggered', context?.step?.guid);
  return context;
});

定时任务未执行

这类问题通常表现为：

  • 到了预期时间没有任何日志
  • 手工调用入口可以成功，自动执行没有发生

优先检查：

  • enable 条件是否满足
  • cron 或 interval 配置是否正确
  • handle 对应入口是否可用
  • 当前环境是否允许定时任务执行
  • 是否存在运行中的并发锁或防抖限制

最小任务配置建议先缩到：

export default {
  demoJob: {
    cron: '0 */5 * * * *',
    enable: true,
    handle: '/api/plugin_example/job/demo',
  },
};

第三方接口调用失败

这类问题通常表现为：

  • 插件逻辑执行到了调用阶段，但外部返回错误
  • 同一功能在不同环境表现不一致
  • 偶发成功、偶发失败

优先检查：

  • 第三方配置是否正确
  • token 是否过期或未正确刷新
  • 网络是否可达
  • 请求体映射是否符合第三方接口要求
  • 当前错误是配置错误、权限错误还是可重试的临时错误

调用前建议先把关键参数打出来：

think.logger.info('[plugin_example] call external api', {
  api: '/tasks',
  platform_id: config.platform_id,
  project_id: project.guid,
});

排查顺序建议

建议按以下顺序排查：

  1. 先确认插件是否已被加载
  2. 再确认注册逻辑是否执行
  3. 再确认业务逻辑是否执行
  4. 最后确认外部依赖是否正常

常见日志与定位点

前端控制台

适合确认：

  • 插件入口是否执行
  • 页面组件是否报错
  • 网络请求是否发出

服务日志

适合确认：

  • 接口是否进入
  • 服务逻辑是否执行
  • 第三方调用是否成功

安装日志

适合确认：

  • 插件包是否处理成功
  • 安装脚本是否执行
  • 重载是否发生

异步任务日志

适合确认：

  • 定时任务是否触发
  • 批处理是否执行
  • 队列是否堆积

典型故障场景

安装成功但页面打不开

优先检查：

  • 页面路由是否注册
  • 前端构建产物是否更新
  • 平台是否已重载

升级后旧配置不兼容

优先检查：

  • 新字段是否有默认值
  • 历史配置是否迁移
  • 页面是否对旧数据做兼容处理

定时任务重复执行

优先检查：

  • 是否缺少并发保护
  • 是否缺少幂等设计
  • 是否有重复调度入口

外部系统超时或鉴权失败

优先检查：

  • 配置是否正确
  • token 是否过期
  • 网络是否可达
  • 错误是否属于可重试类型

推荐阅读