插件项目配置：app.json 插件模式配置、plugin.json 文件详解、声明插件对外暴露的接口

好，咱们接着聊插件项目的配置。说实话，很多新手开发者第一次接触小程序插件时，最容易栽跟头的地方就是配置文件。我自己刚开始做插件开发那会儿，就因为 app.json 里少配了一个字段，折腾了整整一个下午。嗯，今天咱们就把这块彻底讲透。

一、app.json 插件模式配置

先说说 app.json。你可能会问：「这不是小程序的全局配置文件吗？跟插件有什么关系？」

有关系，而且关系很大。当你的项目要作为插件发布时，app.json 需要切换到「插件模式」。说白了，就是告诉微信后台：「我这个项目不是普通小程序，而是一个插件包。」

具体怎么做？看代码：

{
  "pages": [
    "pages/index/index"
  ],
  "plugins": {},
  "pluginMode": true,
  "window": {
    "navigationBarTitleText": "我的插件"
  }
}

关键字段就一个："pluginMode": true。加上这个，你的项目就正式进入插件开发模式了。

另外，pages 字段里只需要保留插件自身的页面。你想想看，插件最终是嵌入到别人的小程序里运行的，所以不需要像普通小程序那样配置一堆页面。

二、plugin.json 文件详解

接下来是重头戏——plugin.json。这个文件是插件的「身份证」，微信后台全靠它来识别你的插件长什么样。

先看一个完整的示例：

{
  "publicComponents": {
    "my-component": "components/my-component/index"
  },
  "pages": {
    "plugin-page": "pages/plugin-page/index"
  },
  "main": "index.js",
  "version": "1.0.0",
  "provider": "wx1234567890abcdef"
}

咱们一个一个拆开讲。

1. publicComponents

这个字段声明了插件对外暴露的组件。说白了，就是告诉使用你插件的人：「嘿，我这里有几个组件，你可以直接用。」

格式是 "组件名": "组件路径"。组件名可以自己起，但建议用有意义的英文名。我在项目中习惯用 kebab-case 命名，比如 my-button、custom-list，这样在别人使用时更直观。

2. pages

插件也可以有自己的页面。比如一个支付插件，可能需要跳转到某个支付结果页。这些页面通过 pages 字段暴露出去。

注意：插件页面不能直接通过 URL 访问，必须由宿主小程序通过 wx.navigateTo 跳转。嗯，这里要记住。

3. main

这个字段指定了插件的入口 JS 文件。通常是一个 index.js，里面可以放一些全局逻辑，比如初始化配置、注册事件等。

我个人习惯在 main 文件里只做两件事：导出插件版本号、初始化一些全局变量。别放太多业务逻辑，否则容易跟宿主小程序的代码冲突。

4. version 和 provider

version 是插件版本号，建议遵循语义化版本规范（比如 1.0.0、2.1.3）。provider 是你的小程序 AppID，这个必须填对，否则发布时会校验失败。

三、声明插件对外暴露的接口

插件不是封闭的，它需要跟宿主小程序「对话」。怎么对话？通过暴露接口。

接口分三种：

接口类型	说明	示例
组件接口	通过 publicComponents 暴露的组件	<my-component />
页面接口	通过 pages 暴露的页面	wx.navigateTo({ url: 'plugin://plugin-page' })
JS 接口	通过 main 文件导出的方法	requirePlugin('myPlugin').getData()

JS 接口这块稍微复杂一点。你需要在 main 文件里用 module.exports 导出方法：

// index.js
module.exports = {
  getVersion: function() {
    return '1.0.0';
  },
  init: function(config) {
    // 初始化插件配置
    console.log('插件初始化完成', config);
  },
  doSomething: function(params) {
    // 一些业务逻辑
    return params.data;
  }
};

宿主小程序那边就可以这样调用：

const plugin = requirePlugin('myPlugin');
plugin.init({ apiKey: 'xxx' });
const version = plugin.getVersion();

四、配置文件的常见坑

最后，分享几个我踩过的坑：

• 路径问题：plugin.json 里的路径是相对于项目根目录的，别写成绝对路径。我见过有人写成 /components/xxx，结果死活找不到组件。
• 组件名冲突：暴露的组件名不要跟宿主小程序已有的组件重名。虽然微信会做隔离，但重名容易引起混淆。我习惯加个前缀，比如 my- 或 plugin-。
• 版本号管理：每次发布新版本，记得同步更新 plugin.json 里的 version 字段。否则微信后台会提示「版本号未更新」，导致发布失败。
• provider 校验：这个前面说过了，再强调一遍——AppID 必须跟小程序后台的一致，大小写都不能错。

好了，关于插件项目的配置，咱们就聊到这儿。说白了，app.json 是开关，plugin.json 是说明书，暴露接口是沟通桥梁。这三样配齐了，你的插件项目才算真正「活」起来。