uni-app 插件制作与发布全指南：从插件目录规范、uni_modules 打包到付费加密与插件市场变现

uni-app 插件制作与发布全指南：从插件目录规范、uni_modules 打包到付费加密与插件市场变现

【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app

导读

本文以 uni-app 官方插件发布文档为核心，系统讲解在 DCloud 插件市场（ext.dcloud.net.cn）上制作、发布、销售与维护插件所需的完整知识：从插件 ID 命名、各类插件（前端组件、页面/项目模板、JS SDK、uts 插件、App 原生插件、HBuilderX 插件、uniCloud 系列）的目录结构要求，到基于uni_modules的模块化开发与一键发布流程，再到付费插件的普通授权版/源码授权版机制、云编译加密、试用与防盗版策略。读完本文，你可以将手头可复用的组件、页面、云函数按规范整理成可发布、可计费、可被使用者一键导入的插件，并理解其背后的加密与授权运行原理。

为什么要提交插件

DCloud 拥有活跃的插件市场，并提供计价销售、广告解锁、赞助、评价等机制。提交插件的动力主要有三方面：

• 分享：写出通用的功能模块时，可以分享给其他有相同需求的人，人人贡献、人人受益；
• 变现：通过赞赏、广告分成、计费销售收获物质回报（只有 uniCloud 插件和 App 原生或 uts 插件支持付费，其他类型插件不能设价格）；
• 荣誉：通过插件下载量、评星、排行收获荣誉。

关于插件变现的完整细节（赞赏、广告解锁、付费销售、账单结算、提现），另见 插件变现指南。

插件制作注意：目录规范与插件 ID

uni 插件本质上是 uni-app 项目下的一部分代码，但提交时需要注意：

• 遵循插件目录规范，其中最重要的是确定插件 ID（详见下方命名规范）；
• 插件包中不应该包含unpackage目录，最好也不包含node_modules目录；
• 插件包中不应该包含版本控制相关文件和目录，如.git、.svn等；
• 前端建议使用 scss 预处理，并引用 uni.scss（或 uni-ui 仓库中的同名文件）中的变量定义，保持各插件风格统一，方便插件使用者通过“搭积木”的方式开发整体风格一致的 App。

插件 ID 命名规范

1. 格式为作者ID-插件英文名称，示例：xiaoming-abc，其中作者 ID 和插件名称只能包含英文、数字；
2. 作者 ID 由插件作者自定义，不能使用DCloud、uni等关键字，长度要求至少 2 位字符；
3. 插件名称需直观表达插件的作用，例如eshop、button等。

仓库中大量插件即遵循此规范，例如 src/uni_modules/uni-actionSheet/package.json 的id为uni-actionSheet、src/uni_modules/uni-badge-view/package.json 的id为uni-badge-view。

uni_modules：推荐的插件组织形式

从 HBuilderX 3.1 起，新增uni_modules，它是 uni 生态的重要模块化方案（详细目录结构与配置见 uni_modules 文档）。自uni_modules发布后，建议插件作者：

1. 首先在自己的项目下建一个uni_modules目录；
2. 在本地开发调试没问题后，对uni_modules下你的插件目录点右键，选择“发布到插件市场”。

插件市场分多种插件分类，下面逐一介绍各类插件的制作与发布要求。

前端组件

前端组件指 uni-app 前端使用 vue/nvue/wxml 等技术开发的、用于页面内嵌的组件，可细分为 vue 组件、uvue 组件、nvue 组件、小程序自定义组件，不包含 uts 原生组件。

以小明开发的 tag 组件（插件 ID 为xiaoming-tag）为例，上传插件市场时，目录结构要求如下：

xiaoming-tag/ ├── components/ │ └── xiaoming-tag/ │ ├── xiaoming-tag.vue // 组件实现 │ └── ... └── ...（仅包含必需文件）

为保证代码简洁，上传插件时仅需包含必需的文件及目录。

依赖三方组件时的打包方式

若组件依赖三方组件，则需将三方组件一起打包上传。假设xiaoming-tag依赖小红开发的 icon 组件（xiaohong-icon），则发布xiaoming-tag插件时，目录结构要求如下：

xiaoming-tag/ ├── components/ │ ├── xiaoming-tag/ // 本插件组件 │ └── xiaohong-icon/ // 被依赖的三方组件一并打包 └── ...

Tips：

• 通用组件、nvue 组件，目录结构要求相同；
• 小程序组件的一级目录，名字需从components变更为wxcomponents，其它结构要求相同；
• 组件不能包含根目录的manifest.json、pages.json、App.vue、main.js等文件。

付费前端插件（uni-app x 云编译加密）

插件市场很早就支持原生插件和 uniCloud 云插件的加密保护，但前端插件（尤其是可编译到 web 和小程序的 ui 库）因其载体特殊开放性，很难做知识产权保护。HBuilderX 4.19 起，DCloud 提供了一种云编译手段来解决前端插件的知识产权保护问题。

加密与云编译机制

插件作者设置加密后，插件使用者下载到的是加密后的版本。在运行、发行对前端代码编译时，uni-app x 的编译器会将加密插件发送到 DCloud 的云编译服务器进行编译，把编译结果混入本地编译工程，从而实现“插件使用者可以使用插件但无法获取插件源码”的效果：

• 这种云编译仅在第一次进行，云编译一次后会有缓存；
• 插件使用者可以获取到编译后的代码，但就像 uni-app (x) 编译后的代码非常难懂、不会有人去改一样，这种方式虽不严谨，但大体上仍能有效保护前端插件作者的知识产权；
• 该过程不会把插件使用者的项目源码整体发送到 DCloud 服务器，云编译和解密的仅包括加密插件本身。

授权版本与绑定规则

• 插件市场所有加密付费的插件，均有普通授权和源码授权两种版本。购买源码授权后，插件作者可以得到插件的完整源码，此时不再发送插件源码到云编译服务器；
• 不管是普通授权版还是源码授权版，都绑定唯一的 appid 和包名。购买者若更换了这 2 个信息中的任意一个，需要重新购买授权（具体参考插件购买协议）；
• 通过开发工具、编译器、运行时的整体配合，DCloud 给前端插件作者提供了以往不存在的知识产权保护方案；包括源码授权版，DCloud 也会检查盗版行为。

加密范围与发布配置

目前前端插件加密仅支持 uni-app x 下uni_modules形式的、符合 easycom 规范的组件，插件可在全平台加密（包括 web 端、app 端）。DCloud 插件市场会自动加密付费插件中所有 vue、uvue、uts、js、ts 文件（除pages、hybrid、static目录外）。

HBuilderX 发布插件界面暂未支持前端组件价格设置，插件作者可在插件package.json中手动配置价格后提交发布（后续 ui 上将支持）。配置方式参考 uni_modules 配置，在package.json的dcloudext下添加sale销售信息，例如：

{ "dcloudext": { "sale": { "regular": { "price": "98.00" }, "sourcecode": { "price": "980.00" } } } }

仓库中免费插件的同构配置可参考 src/uni_modules/uni-actionSheet/package.json（dcloudext.sale中regular.price与sourcecode.price均为0.00即免费插件）。

前端组件付费插件开发注意事项

• 目前仅支持uni-app x项目，不支持uni-app项目，且最低需要 HBuilderX 4.19+；
• 不支持混搭utssdk目录、不支持页面加密，仅支持符合 easycom 规范的组件；可通过依赖的方式配置其他插件（目前仅支持依赖同样加密的插件）；
• 插件需要对外导出方法、类型等内容时，必须在插件根目录index.uts做导出，使用者不能直接引入插件内部的文件；
• 加密组件属性的代码提示配置在发布时云端会自动生成；
• 前端组件付费插件使用时会单独上传至云端独立编译（此时不会包含项目内的其他内容），所以插件不能引入项目内其他目录资源，此类需求可以通过 API 让插件使用者传入对应数据；
• app-android 平台，不支持导出 vue 的 plugin 和 mixin。

前端组件付费插件使用注意事项

• 当项目包含前端付费插件时，首次运行或发行到指定平台会触发付费插件在该平台的云端编译，此时需要电脑处于联网状态，且登录的 HBuilderX 账号具备使用该插件的权限（购买、试用、协作等）。云端编译成功后，后续将使用本地缓存；如果更新了插件版本、HBuilderX 版本或运行时勾选了清除缓存，会再次触发云端编译；
• 不支持直接引入插件内部的文件，仅支持导入插件根目录。例如：

// 正确：导入插件根目录（需要插件作者在 index.uts 中导出 test） import { test } from '@/uni_modules/test-components' // 错误：直接引入插件内部文件 import { test } from '@/uni_modules/test-components/test.uts'

uni-app 前端模板

vue/nvue 页面模板

以小明开发的设置模板（xiaoming-setting）为例，上传插件市场时，目录结构要求如下：

xiaoming-setting/ ├── pages/ │ └── setting/... // 页面文件 ├── manifest.json // 页面模板需包含 ├── pages.json // 页面模板需包含 └── ...

若页面模板依赖其它组件，则需将依赖组件一起打包。假设xiaoming-setting依赖小红开发的 list 组件（xiaohong-list），则发布页面模板时需一并包含components/xiaohong-list/等目录。

依赖管理也可以使用uni_modules：在你的uni_modules目录下的package.json中配置依赖另一个uni_modules，此时不用再包含其他插件的源码。但这种做法无法锁定版本，会在使用者下载你的插件时自动安装最新的依赖。

如果你的页面需要在下载时被注册到使用者的项目的pages.json中，从HBuilderX 3.5.0+插件导入工程时，支持合并页面路由到项目的 pages.json（详见 uni_modules 文档的 pages_init 章节）。

Tips：

• vue 页面模板和 nvue 页面模板目录结构要求相同；
• 页面模板打包时需要包含manifest.json、pages.json等文件。

uni-app 前端项目模板

项目模板无特殊要求，注意满足 uni-app 项目目录结构要求即可。仓库中的 examples/hello-uts 与 examples/hello-uvue 即展示了完整项目应具备的目录骨架（App.vue/uvue、main.js/uts、pages.json、manifest.json、uni.scss、static 等）。

Tips：

• 项目模板打包时不需要包含unpackage目录；
• 项目模板打包时需要包含manifest.json文件，manifest.json里不允许有 appid，包括 DCloud appid 或微信等三方 appid；
• 如果模板中包含 uniCloud 相关的云函数目录（如uniCloud-aliyun、uniCloud-tcb），请选择“uniCloud”->“前后一体项目模板”。如果不使用云函数功能，则应该从插件包中删除 uniCloud 相关目录。

JS SDK

开发 JS SDK 时，对目录结构无特殊要求，仅需将 js 文件命名为插件 ID 即可，例如：xiaoming-md5.js。

Tips：

• 不能包含根目录的manifest.json、pages.json、App.vue、main.js等文件；
• 如果是非uni_modules的 js sdk，使用者下载后会被下载到使用者项目根目录下的js_sdk目录。

UTS 插件

uts 插件开发详见 插件开发文档，这里主要说明 uts 付费插件发布的注意事项。

uts 付费插件分为普通授权版及源码授权版，两种付费方式的区别详见 插件扩展介绍文档。如需发布付费插件，可对插件设置两种版本的价格。DCloud 插件市场会对付费插件自动加密，uts 付费插件加密规则：

• 加密除interface.uts之外的所有 uts 文件；
• 加密utssdk/app-android及utssdk/app-ios目录下的 java、kt、swift 等混编文件。

试用、购买与绑定

• 当插件用户试用插件时，无法查阅这些加密的源码；uts 插件试用只能用于打包自定义基座，不能用于正式发布；
• 如果插件用户购买了普通授权版，也看不到这些加密文件的源码，提交云打包时，会在云端验证并解密文件进行打包；
• 如果插件作者上传插件时设置了提供源码授权版，且插件使用者购买了源码授权版，才能下载到插件的源码；
• 不管是普通授权版还是源码授权版，都绑定唯一的 appid 和包名。购买者更换了这 2 个信息中的任意一个，需要重新购买授权。

Tips：

• uts 加密插件只支持云端传统打包，不支持离线打包、也不支持安心打包，打包最低需要 HBuilderX 3.7.2+；
• 一般提交的 uts 插件仅包含 uts 源码，不建议包含三方 sdk（如 jar），这些应配置成仓储；
• 从HBuilderX 4.81 起，uts 付费插件支持鸿蒙平台；
• 如果发行平台为 web、小程序或鸿蒙，uts 加密插件需要提交云端编译，目前仅支持uni-app x项目，不支持uni-app项目。

uts 插件与 App 原生语言插件的区别

uts 插件和 App 原生插件在功能上重叠，都是原生扩展 uni-app 的能力。从 uts 插件发布后，DCloud 建议插件作者开发 uts 插件替代老的原生插件。它们的具体差别：

• uts 开发和使用更加简单、清晰、小巧；
• uts 插件更新免审核，无需等待 DCloud 管理员审核上架；
• uts 插件天然支持多版本：插件作者更新后，使用者可以不更新，仍然使用之前下载到本地的老版插件；
• uts 插件支持源码版计费，可以卖更高的价格，相关版权由 DCloud 保护，防止盗版和侵权，且很多使用者有源码需求（担心三方 SDK 有不可控代码）。

目前 uni-app 的 ext api 全部基于 uts 实现，一些内置 api（如弹框）也已改成 uts 实现。仓库中的 src/uni_modules/uni-actionSheet 即是一个典型的 uts 类型插件（其 package.json 的dcloudext.type为"uts"，并在uni_modules.uni-ext-api中声明了showActionSheet、hideActionSheet两个 API 在 app 端由 kotlin/swift/arkts 实现）。虽然这些对开发者而言并非需要下载的插件，但本质是内置于 runtime 的 uts 插件。未来 uni-app 的所有官方 api 都会改为 uts 实现，而原生语言插件只会修改较严重的 bug。

在未来，uts 插件将同时支持下一代的 uni-app 的 uvue，以及现有的 vue、nvue；而 app 原生语言插件只支持这一代的 uni-app，无法支持 uvue。包括 uts 组件也将支持 vue 页面，而原生语言插件的组件模式不会支持 vue 页面，只支持 nvue 页面。

注意：uts 插件目前还不支持离线打包，不过插件市场销售的原生语言插件也不支持离线打包。建议有个性化打包需求的开发者使用 HBuilderX 的 cli 来处理自动化打包。

FAQ：为什么原生插件需要审核且很慢，而 uts 插件免审核？因为 uts 插件提交的是源码，可控；原生插件提交给 DCloud 的是编译后的文件，需要人工审核。实际上 uniCloud 插件也是免审核的，同样是源码，凡是提交源码的都免审。

App 原生语言插件

App 原生语言插件需使用 Android/iOS 原生环境开发实现。压缩包格式要求：打开 zip 后根目录需为插件 id 目录，二级目录是 ios、android 子目录及 package.json（uni 原生插件包格式）。

从 uts 插件发布后，DCloud 建议插件作者开发 uts 插件替代老的原生插件，原因见上文 uts 插件与 App 原生语言插件的区别。

HBuilderX 插件

HBuilderX 插件是安装在 HBuilderX 工具里的，是编辑器的插件，不是手机 App 的插件。

uniCloud 插件

云函数模板

云函数模板对文件命名没有特殊要求，但制作插件压缩包时需要注意：

• 当模板中包含一个或多个云函数时，不能只在插件中放入云函数目录，而需要完整的从项目根目录开始，如uniCloud/cloudfunctions/cf123。uniCloud可以接受-aliyun或-tcb后缀（阿里云和腾讯云这两个目录也可以同时存在）；
• 云函数有效的入口文件为index.js，插件包中必须包含至少一个以此命名的文件；
• 涉及账户管理的话，请使用 uni-id。

仓库中 src/uniCloud-aliyun/cloudfunctions 下即存放了多个以index.js为入口的云函数示例，例如 src/uniCloud-aliyun/cloudfunctions/encryption/index.js 就是标准的exports.main入口写法。

付费云函数插件的加密配置

如果上传付费云函数插件，则必须选择要加密的云函数，否则插件试用者可以通过试用流程无限期使用你的插件而不需要付费。

定义加密云函数：为了与 uni_modules 统一规范，废弃原encryptlist.json，需在插件根目录下添加package.json，在uni_modules -> encrypt中配置需要加密的文件，例如：

{ "uni_modules": { "encrypt": [ // 配置要加密的文件，为插件包中真实存在且相对根目录的文件路径，需注意uniCloud目录的后缀需与项目一致 "uniCloud-aliyun/cloudfunctions/function/index.js" ] } }

encrypt数组中可灵活配置uniCloud/cloudfunctions下云函数及公共模块的 js 文件，与原encryptlist.json文件配置整个云函数或公共模块相比更加灵活。

定义好要加密的云函数内容后上传插件，DCloud 插件市场会自动加密这些云函数：

• 当插件用户试用插件时，无法查阅这些云函数的源码，并且**只有在试用期内（一般是 7 天内）**这些加密云函数才能在他部署的服务空间上运行，过了试用期这些云函数将自动失效；
• 即便插件用户购买了插件的普通授权版，也看不到这些加密云函数的源码，但这些云函数可以正常运行在他购买时绑定的服务空间上，且无法上传到其他服务空间；
• 如果插件作者上传插件时同时提供了源码授权版，且插件使用者购买了源码授权版，才能拿到插件的所有源码。

关于普通授权版和源码授权版的区别，详见 插件扩展介绍文档。

从 HBuilderX 3.2.0 版本开始，当发布云端一体项目模板或云端一体页面模板的付费插件时，前端 js 文件也支持加密，设置方式与云函数类似，在uni_modules -> encrypt中定义文件路径，如：

{ "uni_modules": { "encrypt": [ "js_sdk/index.js", "components/demo/demo.js" ] } }

注意：

• 目前只支持付费插件的 js 文件加密，vue 及 nvue 文件无法加密，业务核心逻辑建议写到 js 中；
• 如果发布云端一体项目且包含uni_modules时，不会加密uni_modules目录下的文件，uni_modules下应该作为独立插件发布，分别进行加密配置；
• 如果你的插件配置包含涉密信息、希望保护这些配置不被上传，可参考 uni_modules 插件上传辅助脚本示例。

云端一体页面模板

云端一体页面模板，如果非uni_modules，则为单页面模板，只能放一个页面；如果是uni_modules，可以放任意数量页面。为防止导入时与项目现有代码冲突，需注意以下命名规范：

• 必须包含云函数相关目录（uniCloud/cloudfunctions），可以包含js_sdk、pages、components、static等目录；
• 云函数、公共模块命名需要包含“-”，即带有插件 ID 前缀；
• js_sdk、components、static等目录下的子目录及文件命名需要包含“-”；
• 不能包含根目录的manifest.json、App.vue、main.js等文件；
• 如需注册页面到项目的pages.json中，参考 uni_modules 文档。

前后一体项目模板

与 uni-app 前端项目模板目录结构基本一致，但必须包含 uniCloud 相关目录（uniCloud-aliyun、uniCloud-tcb）。

uniCloud admin 插件

在使用 uniCloud admin 基础框架后，可以进一步集成插件作者写好的 admin 插件，以丰富自己的 admin 系统功能。插件作者可以按本文档提交插件，在插件市场的上传发布页面选择uniCloud分类的Admin 插件。

DB Schema 及验证函数

主要用于提交数据表 schema 及校验函数，所以必须包含uniCloud-aliyun/database或uniCloud-tcb/database目录。仓库中 src/uniCloud-aliyun/database 下的 JSON 文件即此类数据表结构定义。

pages_init 页面注册

该章节文档已迁移至 uni_modules 文档的 pages-init 章节。核心机制：当 uni_modules 插件根目录下存在pages_init.json文件，在插件导入工程时会弹出合并页面路由的 pages.json 修改界面，插件使用者点击确认即可完成插件页面向项目 pages.json 的注册。

插件发布注意与 FAQ

• uni-app 原生 SDK 及 web 项目两个分类下插件发布后需要审核才会生效；
• 插件不能自行下架，如需下架请发邮件到 service@dcloud.io；你也可以把插件标题改为“已废弃”，DCloud 管理员会及时审核处理；
• 如果是非 uni_modules 插件，自己压缩的压缩包注意为标准 zip 格式，不要使用非主流的压缩软件，不要把 rar 等其他格式文件的后缀名改名为 zip。

附：基于 uni_modules 的发布与变现延伸

一键发布流程（HBuilderX）

插件开发完毕后，在 HBuilderX 中可完成发布全流程（详见 uni_modules 文档）：

1. 项目根目录创建uni_modules目录（vue-cli 项目则位于src/uni_modules）；
2. 在uni_modules目录右键“新建 uni_modules 插件”，填写插件 ID、选择插件分类；
3. 本地运行示例项目验证插件功能；
4. 插件目录右键“发布到插件市场”，填写插件信息（更新日志会自动与根目录changelog.md同步）；发布项目模板则在项目根目录创建 package.json 后右键发布；
5. 后续更新版本的操作与首次发布相同，仍为右键“发布到插件市场”。

package.json 中的销售与分类配置

发布插件时，dcloudext节点用于配置插件市场分类标识（type）与销售信息（sale），uni_modules节点用于配置依赖、加密文件与平台兼容性。仓库中的实际范例：

• uts 类型插件：src/uni_modules/uni-actionSheet/package.json（"type": "uts"，并通过uni_modules.dependencies声明对uni-framework、uni-theme、uni-dialogPage、uni-event等插件的依赖）；
• 组件类型插件：src/uni_modules/uni-badge-view/package.json（"type": "component-vue"，声明了完整的platforms.client平台兼容性矩阵，如app-uvue: "y"）；
• 自定义元素类型插件：src/uni_modules/uni-form/package.json（"type": "uts-custom-element"，并通过uni_modules.pages与uni_modules.components映射各平台的 dom2 渲染实现）。

插件市场分类标识（对应package.json -> dcloudext -> type）主要取值如下：

插件依赖与忽略文件

• 在package.json的uni_modules -> dependencies节点配置三方 uni_modules 插件依赖（依赖的插件也必须是 uni_modules 插件）；如果是三方 npm 插件依赖，使用标准的dependencies节点配置；
• 发布到插件市场时通常需要忽略unpackage、.hbuilderx、node_modules等目录，可通过.npmignore文件实现（注意开头有个点）。项目根目录下的.npmignore对发布项目、插件模板生效，uni_modules/插件ID/.npmignore对发布插件生效。

付费插件的通用授权模型

综合来看，插件市场付费插件的授权模型可总结为：

其中 uts/原生插件、前端组件插件的销售与客户端 appid、包名绑定；uniCloud 插件的销售与服务空间绑定；DCloud 为所有销售插件提供了试用机制（详见 插件扩展介绍文档 与 插件变现指南）。

【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app