小程序插件开发：我踩过的那些坑

上个月接了个活，客户要在自己的小程序里接入一个「预约排号」功能。我第一反应是直接写页面，后来一想，这功能他三个小程序都要用，干脆做成插件。结果这一做，踩的坑比预想的多得多。今天就把这次插件开发的经历捋一遍，给想尝试的朋友省点时间。

先想清楚：什么时候该做插件

插件不是万能药。我见过有人把整个项目拆成七八个插件，最后维护起来比单体还累。我的判断标准很简单：

• 这段功能要在多个小程序里复用，且逻辑相对独立；
• 功能边界清晰，比如登录、支付、地图选点、客服；
• 你愿意承担额外的审核和版本管理成本。

如果只是单个项目里的模块，用自定义组件就够了，别上插件。插件发布要走审核，每次更新都得重新提审，这个成本很多人一开始没算进去。

开发前的准备工作

做插件得先在小程序后台申请，拿到 AppID 之后，在开发者工具里新建「小程序插件」项目。这里有个容易忽略的点：插件项目和小程序项目是两套目录结构，插件里没有 app.json 那套页面配置，取而代之的是 plugin.json。

{
  "publicComponents": {
    "booking-panel": "components/booking-panel/index"
  },
  "pages": {
    "booking-list": "pages/booking-list/index"
  },
  "main": "index.js"
}

publicComponents 是对外暴露的组件，pages 是插件自己的页面。只有写进这里的，宿主小程序才能用。我第一次没配 publicComponents，宿主那边死活引不进来，查了半天文档才发现。

宿主怎么引入

宿主小程序要在 app.json 里声明插件，然后在页面里用 plugin:// 协议引用组件或跳转页面。

{
  "plugins": {
    "myBooking": {
      "version": "1.0.0",
      "provider": "插件AppID"
    }
  }
}

<booking-panel plugin-id="myBooking" />

注意组件标签名要用插件里注册的名字，不是文件名。这个细节坑过我不止一次。

真正麻烦的地方：通信与作用域

插件和宿主之间是隔离的。插件拿不到宿主的全局数据，宿主也直接读不到插件内部状态。所有交互都得走属性传递和事件回调，或者用 requirePlugin 拿插件暴露的接口。

我这次的做法是：插件暴露一个 init 方法，宿主把用户信息和接口地址传进去；插件内部通过 triggerEvent 往外抛事件，宿主监听后自己处理业务逻辑。这样职责清楚，插件不碰宿主的登录态，宿主也不用关心插件怎么渲染。

一个血泪教训：插件里不要直接调宿主小程序的接口路径，把请求封装成可配置的，否则换个项目就得改代码重新提审。

审核与版本的那些事

插件审核比普通小程序还严一点。我提交时被打回过一次，原因是插件简介写得太笼统，审核员看不出具体用途。后来把功能点、使用场景、截图都补上才过。

还有版本管理。插件发布后，宿主引用的是具体版本号。你更新了插件，宿主不会自动升级，得手动改 version 再提审。所以我在插件里尽量保持接口向后兼容，新增字段而不是改老字段，减少宿主被迫升级的次数。

值不值得做

说实话，如果只服务一两个项目，插件带来的审核和联调成本可能超过收益。但如果你手里有一批同类型的小程序，或者想把某个能力做成产品对外提供，插件是个正经路子。它把能力封装成标准件，宿主接入只要几行配置，长期看是省事的。

我的建议是：先用自定义组件把功能跑通，验证确实要复用，再抽成插件。别一上来就奔着插件去，容易在隔离机制和审核流程上耗掉太多精力。先把业务跑起来，架构的事可以晚一步。