唐山小程序插件开发：踩过的坑与实战心得

做小程序这几年，插件这个模块我踩的坑比页面开发加起来还多。前阵子接了个唐山本地连锁超市的活儿，需求很典型：会员卡、积分、优惠券三件套，还要在三个小程序里复用。如果每个都重写一遍，工时直接翻三倍。最后是用插件解决的，过程不算顺利，这里把过程和一些细节记下来。

先搞清楚插件能干什么、不能干什么

很多同行第一次接触插件，会误以为它就是一个组件库。其实微信小程序插件是一个独立的代码包，有自己的 app.json、自己的页面和组件，可以被其他小程序引用。它和普通 npm 包最大的区别是：插件运行在宿主小程序的环境里，但代码和宿主是隔离的。

几个容易忽略的限制：

• 插件不能直接调用宿主的 wx.login 拿到的 code 去换 openid，得通过 plugin.login 走插件自己的登录态。
• 插件内不能使用 wx.getUserProfile 这类涉及用户敏感信息的接口，需要宿主页面授权后传参进来。
• 插件包体积有上限，主包加分包算下来不能超过 2MB，功能别塞太满。
• 插件不能调用 wx.request 访问未配置的域名，网络请求域名要在插件后台单独配置。

这几点在官方文档里都有，但真正动手时，往往要撞一次才记得住。我第一次做会员卡插件时，卡在登录态上整整半天，后来才想明白插件得自己维护一套 session。

一个可复用的会员卡插件结构

以那个唐山超市项目为例，插件的目录大致是这样：

plugin/
  ├── plugin.json          // 插件配置文件
  ├── components/
  │   ├── member-card/     // 会员卡组件
  │   └── coupon-list/     // 优惠券列表
  ├── pages/
  │   ├── member-center/   // 会员中心页
  │   └── points-detail/   // 积分明细
  └── utils/
      └── request.js       // 统一请求封装

plugin.json 里要声明对外暴露的组件和页面：

{
  "publicComponents": {
    "member-card": "components/member-card/index",
    "coupon-list": "components/coupon-list/index"
  },
  "pages": [
    "pages/member-center/index",
    "pages/points-detail/index"
  ],
  "main": "index.js"
}

宿主小程序在 app.json 里声明插件，然后在页面 json 里引入组件：

{
  "usingComponents": {
    "member-card": "plugin://memberPlugin/member-card"
  }
}

这里有个细节：插件的 plugin:// 路径必须和插件后台登记的 appid 对应，开发阶段用开发者工具里的插件调试模式，很容易漏掉 appid 配置，导致组件一直渲染不出来。

插件和宿主的数据交互

插件和宿主之间不能直接共享 data，得靠事件和属性。会员卡组件我设计了两个关键属性：memberInfo 和 theme，宿主把用户信息和主题色传进来，插件内部只负责渲染和交互。

反过来，插件里用户点击「去兑换」这类操作，用 triggerEvent 抛给宿主处理：

// 插件组件内部
this.triggerEvent('exchange', { couponId: this.data.couponId })

// 宿主页面
<member-card bind:exchange="onExchange" />

这种单向数据流的设计，一开始觉得麻烦，后来发现好处很大：插件不依赖宿主的任何全局状态，换个项目直接搬过去就能用。那个唐山超市后来又在隔壁城市开了分店，新小程序接入插件只花了半天。

本地项目里几个真实的坑

1. 插件登录态和宿主登录态要分开管

宿主用 wx.login 拿到 code 换自己的 token，插件这边要用 plugin.login 拿插件自己的 code。两者不能混用，否则插件后台的 openid 和宿主对不上。我的做法是插件内部封装一个 ensureLogin()，首次调用时走插件登录，把插件 token 存在 wx.setStorageSync 里，键名加前缀避免和宿主冲突。

2. 样式隔离比想象中严格

插件组件默认样式隔离，宿主的全局样式进不来。这本来是好事，但做会员卡时，宿主想统一改圆角和字体，就得通过 CSS 变量传进去。我在插件里预留了 --card-radius、--card-bg 几个变量，宿主在页面根节点设置即可，比暴露一堆属性干净。

3. 真机调试和开发者工具表现不一致

开发者工具里插件页面跳转正常，真机上偶尔白屏。排查下来是插件页面路径写成了相对路径，真机解析失败。插件内跳转统一用绝对路径 /pages/xxx/index，这个习惯建议一开始就养成。

什么时候值得做成插件

不是所有功能都适合插件化。我的判断标准比较简单：同一套业务逻辑要在两个以上小程序里复用，且这些小程序归属不同主体或不同项目，才值得抽插件。如果只是自己一个项目内部复用，抽成自定义组件或者 npm 包就够了，插件带来的调试成本和发布审核流程反而拖慢节奏。

另外插件发布要走审核，版本更新不是即时生效的，宿主小程序得手动升级插件版本。这点在给客户做交付计划时要提前说清楚，别让客户以为改完就上线。

在唐山做小程序开发这段时间，接触的本地客户以零售、餐饮、本地生活服务为主，这类项目功能重合度高，插件化的收益其实挺明显。知码客这边现在的做法是，把会员、预约、核销这几个高频模块逐步沉淀成插件，新项目接入时省下的时间可以多花在业务细节上。如果你也在做类似的多项目复用，不妨从最小的一个组件开始试，别一上来就想着做全家桶。