当前位置：首页 > article >正文

Uniapp开发微信小程序插件的一些心得

article 2026/4/1 5:47:36

一、uniapp 开发微信小程序框架搭建

1. 通过 vue-cli 创建 uni-ap

// nodejs使用18以上的版本
nvm use 18.14.1
// 安装vue-cli
npm install -g @vue/cli@4
// 选择默认模版
vue create -p dcloudio/uni-preset-vue plugindemo
// 运行 uniapp2wxpack-cli
npx uniapp2wxpack --create

2. 手动在项目根目录创建插件开发需要的 project.config.json

并且内容 miniprogramRoot 和 pluginRoot 属性按以下填写，并且在 appid 字段中自行填写真实的 appid（小程序的 appid）

// project.config.json
{"miniprogramRoot": "miniprogram/","pluginRoot": "uniSubpackage/","compileType": "plugin","setting": {},"appid": "xxxxxxxxx","projectname": "plugindemo","simulatorType": "wechat","simulatorPluginLibVersion": {},"condition": {}
}

3. 在 src 目录下手动创建 plugin.json，

main 属性必须按以下内容填写，也就意味着插件的接口文件指向 src/main.js（因为打包后路径会变成 common/main.js）

{"publicComponents": {"hello-component": "components/test"},"pages": {"yuwen-page": "pages/textbook/index"},"main": "common/main.js"
}

4. 运行命令编译

npm run dev:mp-weixin-pack-plugin （开发模式）
npm run build:mp-weixin-pack-plugin （生产模式）

此部分详细内容可参考uniapp + uniapp2wxpack

5 生成的完整目录如下

6 打包生成的目录

7 增加插件文档支持

在项目根目录增加doc文件夹，新建README.md文件，作为插件的文档
项目打包后，手动将doc文件夹拷贝到 dist/dev/mp-weixin-pack-plugin目录
微信开发者工具单击右键doc文件夹，上传插件文档
在微信公众平台，插件基本信息，更新插件文档

二、uniapp 开发微信小程序插件遇到的问题及解决

1 当前 uniapp 开发插件，插件内部跳转报错 `navigateTo:fail rejected due to no permission currently`

经过定位问题，发现属于uniapp的框架问题，uniapp封装了wx.和uni.，导致uni.navigateTo、uni.request 的权限都是主小程序的，而不是插件内的，在编译生成的代码里把对应的硬改成 wx. 的方法，程序不回报错，但是这样是治标不治本，只能说定位到问题出现在这块儿。

解决办法：

将`wx.js` 替换 `/node_modules/@dcloudio/uni-mp-weixin/dist/wx.js`
将`index.js ` 替换 `/node_modules/@dcloudio/vue-cli-plugin-uni/lib/mp/index.js`
index.js下载地址和 wx.js下载地址
uniapp官方原贴

2 插件总线通信问题

按照微信官方文档，在plugin.json可以设置main，提供一个index.js给到小程序调用（通过requirePlugin()方法获得），然后本帖的框架main.js是项目的入口程序，不能通过module.export导出。

解决方案：

uniapp预置了一个__uniPluginExports接口，可以在上面写index.js需要暴露的方法和功能。

// src/main.js
...
const app = new Vue({
...
})// 用来给引用的小程序使用的，相当于原生小程序插件写法的index.js
__uniPluginExports = {eventBus: {},...,其他方法
}

三、插件-小程序通过事件总线通信

1 插件可以预置一个eventBus事件总线，供插件和小程序通信使用。

对应__uniPluginExports的eventBus，小程序通过requirePlugin()获取并使用。

// 用 JS 实现简易版的事件总线
class EventBus {constructor () {this._events = new Map()}// next 触发某个行为next (type, ...args) {let handler = this._events.get(type)if (Array.isArray(handler)) {// 如果 handler 是数组，说明有多个监听者，需要依次触发里边的函数for (let i = 0; i < handler.length; ++i) {if(handler[i]){if (args.length > 0) {handler[i].apply(this, args)} else {handler[i].call(this)}}}} else {if (handler) {// 单个函数的情况直接触发即可if (args.length > 0) {handler.apply(this, args)} else {handler.call(this)}}}return true}// subscribe 订阅/监听某个行为subscribe (type, fn) {const handler = this._events.get(type) // 获取对应事件名称的函数清单if (!handler) {this._events.set(type, fn)} else if (handler && typeof handler === 'function') {// 如果 handler 是函数，说明当前只有一个监听者// 再次添加监听者，需要改用数组储存this._events.set(type, [handler, fn])} else {// 已有多个监听者，直接往数组里 push 函数即可handler.push(fn)}}// destroy 销毁事件destroy (type, fn) {const handler = this._events.get(type) // 获取对应事件名称的函数清单// 如果是函数，说明只有一个监听者，直接删除if (handler && typeof handler === 'function') {this._events.delete(type)} else {handler.splice(handler.findIndex(e => e === fn),1)}}
}export const eventBus  = new EventBus()

2 插件可以通过requireMiniProgram()获取小程序app.json暴露出的index.js，

并可以根据配置来初始化插件的一些信息。

// 宿主小程序的app.json
{"pages": [],"plugins": {"plugin":{"version": "","provider": "插件appId","export": "index.js","genericsImplementation": {"plugin-page": {"mp-view": "这里是宿主小程序自定义组件的路径"}}}}
}

// 宿主小程序index.js, 暴露给插件的一些配置项
module.exports = {....
}

// 插件获取小程序暴露的index.js
const miniProgramExports = requireMiniProgram(); // 接收小程序通过index.js传过来的数据

3 通过事件总线实现小程序插件通信

插件给小程序发消息

import { eventBus} from '@/utils/eventBus';eventBus.next('方法名', { 
... // 传参
});// 在页面|组件销毁前，记得执行destory()方法注销事件订阅
eventBus.destory('方法名')

小程序订阅插件消息

const plugin = requirePlugin('插件名');
plugin.eventBus.subscribe('事件名', () => {
// 回调函数
})

4 引用小程序的自定义组件

插件开发官方原贴

4.1 page.json 配置componentGenerics

// 插件目录 src/pages.json
{"pages": ["path": "pages/index/index","style": {"navigationBarTextStyle": "black","navigationBarBackgroundColor": "#FFFFFF","backgroundColor": "#F8F8F8","navigationBarTitleText": "课本朗读",//  配置componentGenerics"componentGenerics": {"mp-view": true}}]
}

4.2 plugin.json配置页面标签

// 插件 src/plugin.json
{// 配置公共组件"publicComponents": {},"pages": {"plugin-page": "pages/index/index"},"main": "common/main.js"
}

4.3 插件pages/index/index.vue页面使用mp-view

<template><view>...<mp-view></mp-view></view>
</template><script>
...
</script><style lang="scss" scoped>
...
</style>

4.4 宿主小程序app.json配置genericsImplementation, 声明自定义组件

// 宿主小程序的app.json
{"pages": [],"plugins": {"plugin":{"version": "","provider": "插件appId","export": "index.js","genericsImplementation": {"plugin-page": {"mp-view": "这里是宿主小程序自定义组件的路径"}}}}
}

四、插件预置方法

1 微信不支持宿主小程序直接从插件页面跳转宿主小程序的页面。所以可以通过插件预置的方法实现

// 插件src/main.jsimport { eventBus } from '@/utils/eventBus ';...// 用来给引用的小程序使用的
__uniPluginExports = {eventBus: eventBus,/*** 在插件内跳转到小程序页面* @param url{string} 页面 URL* @returns {Promise<unknown>}*/jumpPage: function (url) {return new Promise((resolve, reject) => {uni.navigateTo({url: url,success(e) {resolve(e);},fail(e) {reject(e);},});});},jumpPageBack() {uni.navigateBack({fail(e) {console.log('uni.navigateBack', e);},});},/*** 在插件内跳转到小程序页面,并关闭当前页面* @param url{string} 页面 URL* @returns {Promise<unknown>}*/jumpPageRedirect: function (url) {return new Promise((resolve, reject) => {uni.redirectTo({url: url,success(e) {resolve(e);},fail(e) {reject(e);},});});},/*** 在插件内跳转到小程序页面* @param url{string} 页面 URL* @returns {Promise<unknown>}*/reLaunch(url) {return new Promise((resolve, reject) => {uni.reLaunch({url: url,success(e) {resolve(e);},fail(e) {reject(e);},});});}
}

宿主小程序调用插件跳转路由方法

const plugin = requirePlugin('插件名');
plugin.jumpPage('这里传入小程序的url')

2 某些场景，插件需要跳转h5页面，微信小程序插件不支持webview，所以需要使用宿主小程序跳转webview页面

具体步骤如下：

插件通过事件总线触发一个自定义的webview事件通知宿主小程序，并传入h5的url
宿主小程序订阅webview的事件，得到h5的url地址
宿主小程序调用插件暴露出的jumpPage方法，跳转自身webview页面，并保存h5地址
宿主小程序在webview页面拿到h5地址并渲染页面