1. 为什么要写安卓原生插件先搞懂你的真实需求做 uni-app 开发的同学大概率都遇到过这么几个场景项目跑得好好的突然有个功能只能用原生代码实现比如读取设备唯一标识、对接某个只有安卓版 SDK 的硬件、调用系统级 API 完成蓝牙配对或 NFC 读写。这时候你打开 HBuilderX 的插件市场翻半天要么没找到合适的要么找到的插件年久失修作者邮箱都变成死链了。然后你开始纠结是硬着头皮写原生还是砍掉这个功能我的建议是能写就写。尤其在安卓平台上原生插件开发的难度比很多人想象中低得多本质上就是写一个 Android 的 Module然后通过 uni-app 提供的桥接层暴露给 JS 调用。你不需要成为安卓大牛只需要掌握 Activity、Intent、广播、回调这些基础概念再加上一点 Java 或 Kotlin 的语法能力就足够覆盖 90% 以上的常见需求。这篇博文我会带你完整过一遍从环境准备、插件编写、项目集成到真机调试的整个流程顺便把我在实际项目中踩过的坑一并交代清楚。先说清楚什么人需要看这篇内容。如果你用过 uni-app但第一次接触原生开发如果你接手的项目里已经有一堆 .aar 文件但你从来没搞明白它们是怎么跑起来的如果你的业务场景是需要持续迭代原生模块而不是临时找个人写个一次性 Demo——那么这篇文章就是给你准备的。如果你只是想把一个现成的 jar 包塞进项目里不涉及自己写代码那流程会更简单我在后面也会顺带提一下。2. 开发前需要理解的核心机制JS 与原生到底怎么通信很多人一提到“原生插件”就头皮发麻本质上是被“原生”两个字吓到了。其实 uni-app 安卓原生插件做的事情非常单纯在 JS 层和安卓原生层之间建立一座桥让数据能双向流动。这座桥有一个官方名字叫“Module 扩展”它走的通信机制非常简单直接你不需要深入理解 Binder 或 JNI只需要掌握下面几个概念。2.1 uni-app 安卓原生插件的两种形态先说插件载体。uni-app 安卓原生插件有两种打包形态一种是Module 扩展纯逻辑模块一种带界面的Component 扩展原生视图偶尔还会用到UniJS 扩展JS 与原生互通。绝大多数业务场景——比如获取设备信息、加密数据、调用系统能力、对接第三方 SDK——用 Module 扩展就够了。只有当你需要在页面里嵌入一个原生控件比如自定义相机预览、地图、扫码框才需要写 Component 扩展。不管你写哪种形态你的代码最终都会被编译成一个安卓的 Module 或者 Library 工程然后在 HBuilderX 中配置并调用。从项目结构上看它就是一个标准的 Android Library Module里面注册一个继承自UniModule的类然后在方法上打上注解就这么简单。真正决定复杂度的不是插件本身而是你要对接的那套 SDK 或者系统 API 有多麻烦。提示第一优先级判断——你的需求用 Module 能不能搞定能就别写 Component。原生视图涉及生命周期同步、事件传递、上下文切换复杂度是 Module 的好几倍而且遇到问题很难在社区里搜到现成答案。2.2 通信模型JS 调方法原生回回调理解通信模型你就掌握了插件的骨架。整个调用过程可以简化为三步JS 层通过uni.requireNativePlugin(插件名)拿到插件实例然后调用实例上的某个方法比如module.getDeviceId({}, callback)。原生层对应的方法被触发方法签名上标注了UniJSMethod注解的方法会接收一个JSONObject类型的参数这就是 JS 传来的数据。原生代码处理完业务逻辑后通过回调对象把结果返回给 JS。JS 层的 callback 收到结果继续处理后续逻辑。你可能会问如果原生的某个操作很耗时比如网络请求、加解密大文件这时候能不能异步处理当然能。UniJSCallback是支持异步回调的只要你在原生层把回调对象保存下来在子线程中执行完任务后再调用它的invoke方法就能把结果原路送回 JS 层完全不需要阻塞 UI 线程。这也是我特别建议所有耗时操作都扔到子线程去做的原因。顺着这个模型继续往下看你会发现一个趋势插件开发的核心工作不是写桥接代码本身而是根据业务需求决定哪些能力放到原生层、以什么粒度暴露给 JS、以及如何处理数据格式的转换。设计得好的插件JS 层调用起来像调用普通 JS 方法一样顺滑设计得差的插件动辄要求 JS 层传一堆连原生开发都记不住的参数。2.3 为什么选原生插件而不是纯 JS 方案有时候你会在 uni-app 社区看到一些人在争论某个功能明明可以用 HTML5 Plusplus.android或者 renderjs 实现为什么非要写原生插件我的回答是看场景。如果是十几行的逻辑比如获取一个系统剪贴板、判断当前网络类型用 plus.android 直接调 Java 类确实方便一个页面里写完就完事不需要打包原生插件但如果你的功能涉及复杂的异步流程、需要跨页面复用、性能要求高或者要对接一个自带 UI 的原生 SDK纯 JS 方案会急剧膨胀维护起来非常痛苦。原生插件的优势在于它是一段独立的、可复用的、可独立演进的原生代码和 JS 层完全解耦接口只要定好两边可以并行开发。另外一个经常被忽视的因素是性能。JS 和原生之间的桥接是有开销的每次调用都要做参数装箱、类型转换、跨线程调度。如果一段逻辑需要在循环里执行几百次或者处理比较大的二进制数据把它整个下沉到原生层性能差距是肉眼可见的。举个具体例子我做过一个图片批量压缩的功能纯 JS 实现压缩一张 3MB 的图片大约需要 1.2 秒换成原生插件处理多张压缩总耗时反而更短内存占用低了不止一个级别。3. 从零搭建原生插件开发环境含离线 SDK 完整配置开发原生插件HBuilderX 只是你的“壳工程”管理工具真正的战场在 Android Studio。我见过不少人在这一步就卡住了主要原因是官方文档写得太简略很多细节要靠自己试错。下面我把整个环境搭建流程和我踩过的坑一次性给你整理清楚。3.1 需要的工具和版本匹配逻辑你需要准备的东西如下HBuilderX建议用最新正式版注意一年内更换过版本的话离线 SDK 也要同步更换。Android Studio推荐 3.5 以上版本我目前用的是最新稳定版建议你直接用官网下载的版本不要用某些第三方修改版。JDK推荐 JDK 8 和 JDK 11 各装一份。很多老 SDK 还在用 JDK 8 的语法而新版的构建工具会强制要求 JDK 11。uni-app 离线 SDK这是核心在 DCloud 官网的“原生开发者支持”页面可以下载里面是带 HBuilderX 引擎的完整安卓工程。版本匹配这一点我要重点强调。离线 SDK 的版本必须和你的 HBuilderX 版本严格对应不能拿 3.99 的 HBuilderX 去用 3.9 的 SDK否则打出来的包调本地插件时会报类找不到、方法找不到这类莫名其妙的问题。我自己犯过这个错误当时整整排查了一个下午最后发现就是版本不匹配导致的。3.2 拿到离线 SDK 后先做掉这 5 件事下载完离线 SDK解压之后你会看到一个HBuilder-Integrate-AS目录这就是官方给你准备好的壳工程。第一次打开这个工程之前强烈建议你先手动做完下面这几件事拷贝libs目录下的所有.aar和.jar文件到你的主工程的libs目录。这些都是引擎运行所需的依赖缺一个后面都会出问题。确认build.gradle里的compileSdkVersion与targetSdkVersion。这两个值不能低于离线 SDK 要求的版本否则构建报错都算轻的运行时会直接崩溃。修改包名。默认壳工程的包名一般是com.android.application之类的你要改成自己应用的包名而且后面在 HBuilderX 里配置的包名要和这里完全一致。把assets/data/dcloud_control.xml里的appid改成你自己的应用标识。这个 appid 是 HBuilderX 项目里的 appid而不是应用市场里应用包名别搞混了。跑一遍官方自带的_UniPlugin模块示例。这个示例里面包含了 Module 和 Component 两种示例代码先确认你能跑通它再开始写自己的插件。注意不要一上来就在官方工程里直接改代码建议复制一份出来改留一个干净的原版工程当参考。原版工程在报错时可以对比文件差异快速定位问题。3.3 在 HBuilderX 中配置本地插件让插件能被你的项目加载插件代码写好了壳工程也准备好了接下来你要在 HBuilderX 项目里进行配置让前端代码能真正调用到原生模块。打开项目的manifest.json找到“App 原生插件配置”一栏点击“选择本地插件”然后选择你的插件目录。这个目录下必须要有完整的package.json和一个 Android 工程目录HBuilderX 会自动识别。这里有个关键点HBuilderX 里的“本地插件”只是开发调试时用的它不会把你的原生代码真正打包进安装包。真正在手机上跑起来的时候需要你使用“云端打包”或者“本地打包”的方式让原生插件代码参与编译。如果你的项目是云打包需要把插件上传到 DCloud 插件市场设为私有插件然后使用如果你追求速度和稳定性本地打包更推荐这也是我主要采用的方式。本地打包的流程是把你在 Android Studio 中写好的原生插件模块打包成.aar放进离线 SDK 壳工程的libs目录再在壳工程的assets/data/dcloud_control.xml里确认插件配置最后用 Android Studio 直接编译生成 APK。这个流程来来回回会有一点繁琐但等你跑通一次以后后续的迭代就很顺了。4. 手写一个原生 Module 插件从建模块到能跑通全流程工具准备好之后我们就进入正题自己动手写一个 Module 插件。我以一个“获取设备唯一标识并生成短码”的插件为例把这个过程完完整整讲一遍。这个例子的好处是它不依赖任何第三方 SDK你不需要跑到某个官网去申请 key跟着做就能跑通。4.1 新建 Library Module 并配置 Gradle在 Android Studio 中打开你的壳工程选择File - New - New Module选择Android Library模块名建议取deviceinfo之类的名字。创建完成后打开这个模块的build.gradle做以下几件事将compileSdkVersion与壳工程保持一致。添加 DCloud 的依赖。这一步要在根目录的build.gradle里先加上 DCloud maven 仓库地址。我这里直接贴出关键代码片段// 根目录 build.gradle 中的 allprojects.repositories allprojects { repositories { google() mavenCentral() // DCloud 仓库 maven { url https://dl.bintray.com/dcloud/Android } maven { url https://maven.aliyun.com/repository/releases } } }然后在你的 Module 的build.gradle里加入依赖dependencies { implementation fileTree(dir: libs, include: [*.jar, *.aar]) implementation com.alibaba:fastjson:1.2.83 compileOnly com.android.tools.build:gradle:4.0.0 compileOnly com.dclouduni:uniapp-release:3.8.12 }注意这里用的是compileOnly因为最终打包时引擎依赖会由壳工程提供你的模块里如果用了implementation或者api反而可能出现依赖冲突。4.2 编写实现类继承 UniModule 并暴露方法接下来创建DeviceInfoModule.java关键代码如下package com.example.deviceinfo; import android.content.Context; import android.os.Build; import android.provider.Settings; import android.text.TextUtils; import com.alibaba.fastjson.JSONObject; import com.taobao.weex.annotation.JSMethod; import com.unicorn.uniplugin.UniModule; import java.security.MessageDigest; import java.util.Locale; public class DeviceInfoModule extends UniModule { /** * 获取设备唯一标识并返回经过 MD5 处理的短码 * JS 调用方式module.getDeviceId({}, callback) */ JSMethod(uiThread false) public void getDeviceId(JSONObject options, UniJSCallback callback) { if (mUniSDKInstance null || mUniSDKInstance.getContext() null) { invokeCallback(callback, -1, context is null); return; } Context context mUniSDKInstance.getContext(); String androidId Settings.Secure.getString(context.getContentResolver(), Settings.Secure.ANDROID_ID); if (TextUtils.isEmpty(androidId)) { androidId Build.SERIAL; } String result md5(androidId).substring(0, 16); JSONObject data new JSONObject(); data.put(deviceId, result); data.put(androidId, androidId); invokeCallback(callback, 0, data); } private String md5(String input) { try { MessageDigest md MessageDigest.getInstance(MD5); byte[] digest md.digest(input.getBytes(UTF-8)); StringBuilder sb new StringBuilder(); for (byte b : digest) { sb.append(String.format(%02x, b)); } return sb.toString(); } catch (Exception e) { return ; } } private void invokeCallback(UniJSCallback callback, int code, Object data) { if (callback null) return; JSONObject result new JSONObject(); result.put(code, code); result.put(data, data); result.put(message, code 0 ? success : failed); callback.invoke(result); } }先解释几个关键点。JSMethod(uiThread false)这个注解表示这个方法不需要在 UI 线程执行因此可以放心做耗时操作。如果不加这个参数默认是uiThread true意味着方法会在主线程运行遇到耗时逻辑就会卡界面。mUniSDKInstance是UniModule基类中的一个字段它代表了当前插件所依附的原生宿主通过它可以拿到Context、Activity、View等关键对象这是插件和页面交互的核心入口。回调部分我这里统一封装了一个invokeCallback方法把 code、data、message 包装成一个 JSON 返回这样 JS 层解析时就非常统一不用每一个接口单独写一套判断逻辑。4.3 配置 package.json 并让插件“被识别”光有 Java 代码还不行你需要一个package.json文件来告知 uni-app 这个插件的信息{ name: DeviceInfo-Module, id: DeviceInfo-Plugin, version: 1.0.0, description: 获取设备唯一标识的原生插件, _dp_type: nativeplugin, _dp_nativeplugin: { android: { plugins: [ { type: module, name: DeviceInfo-Plugin, class: com.example.deviceinfo.DeviceInfoModule } ], integrateType: aar, minSdkVersion: 21 } }, modules: { DeviceInfo-Plugin: { moduleClass: com.example.deviceinfo.DeviceInfoModule } } }几个字段的含义id是这个插件包的唯一标识你在manifest.json里引用插件时填的就是这个值type为module表示这是一个普通 Module 插件如果是组件扩展就写componentclass是全限定类名必须和 Java 代码中的包名类名完全匹配。配置完毕后回到 HBuilderX 项目在manifest.json的“App 原生插件配置”中点击“选择本地插件”找到并选中这个插件目录。此时前端代码就可以这样调用了const deviceInfo uni.requireNativePlugin(DeviceInfo-Plugin); deviceInfo.getDeviceId({}, (result) { console.log(code result.code); console.log(deviceId result.data.deviceId); });这一步能跑通说明桥接已经建立成功。4.4 真机运行与本地打包的完整流程到这里你需要选择一个方式把这个插件跑在真机上。我一般分成两个阶段。第一阶段HBuilderX 真机运行调试。用数据线连接安卓手机在 HBuilderX 中点击“运行到手机或模拟器”。此时 HBuilderX 会把你的 JS 代码通过无线调试通道推送到手机同时运行在这个通道上的原生引擎会加载本地插件。如果你的插件代码有问题这里会直接抛异常比较好排查。需要注意的是真机运行模式下HBuilderX 使用的是它自己内置的引擎和 base module不会加载你自己在 Android Studio 里写的壳工程。也就是说如果你在壳工程里做过其他原生改动比如改过 AndroidManifest.xml 里注册的 Activity真机运行时这些改动不生效。这个阶段的重点只是验证插件逻辑的对错。第二阶段本地离线打包生成正式 APK。当你确定插件功能正确、JS 调用逻辑没有问题之后就要把插件打包进正式 APK 了。在 Android Studio 壳工程中执行构建gradle assembleRelease或者直接点 Android Studio 右侧 Gradle 面板的:app:assembleRelease。构建完成后APK 输出在app/build/outputs/apk/release/目录。把这个 APK 安装到手机上再跑一遍功能确认插件在“无 HBuilderX 调试环境”下依然正常工作。这一步非常重要因为很多依赖 HBuilderX 调试通道的 API 在正式包中不可用例如某些和调试器相关的回调。注意如果你在开发时用到了网络接口请提前确认你的AndroidManifest.xml中已经加入了uses-permission android:nameandroid.permission.INTERNET /权限。很多新手做完插件后反馈“网络请求失败”其实就是漏了这行权限声明。4.5 一个真实的踩坑记录回调必须回调到正确线程我在开发第一个插件时遇到过这样一个问题插件方法在子线程中执行了耗时任务任务完成后直接调用了callback.invoke()结果发现 JS 层偶尔收不到回调或者收到回调后页面上的setData失效。排查了很久最终确定原因是callback.invoke()的调用线程不是 UI 线程。uni-app 的 JS 层回调要求必须回到 JS 线程执行直接在某些原生回调线程里 invoke 会丢失。解决办法就是用Handler切换到主线程new Handler(Looper.getMainLooper()).post(() - callback.invoke(result));这个习惯养成之后我在后面写的每一个插件里都强制规范不管当前代码在哪个线程最终执行callback.invoke之前必须切换到主线程。这里也提醒所有刚开始写插件的朋友“线程问题”是原生插件开发中最高频的坑没有之一。5. 需求千变万化那些高频场景的插件开发要点通过上面的流程你已经能写一个最小可用的原生插件了。但真实业务中需求往往不是给你一个设备 ID 这么简单。下面把最常见的几个需求方向和对应的实现要点梳理出来每个我都会根据实际经验给出一些建议方便你少走弯路。5.1 带 UI 的组件插件怎么入门如果你需要原生自绘界面比如一个自定义扫码框、一个视频播放器、一个地图覆盖物就得使用组件插件了。这类插件和 Module 插件的写法差别比较大继承类不是UniModule而是UniComponent。要重写onCreateView方法返回一个原生的View。要让 JS 层能修改组件属性需要实现IWXInstance相关的属性方法要让组件向 JS 层发送事件需要调用mUniSDKInstance.fireEvent。举个例子一个最简单的“红色背景原生 View”组件Java 代码如下public class TestComponent extends UniComponentView { Override public View onCreateView() { TextView textView new TextView(mContext); textView.setText(我是原生组件); textView.setTextColor(Color.WHITE); textView.setBackgroundColor(Color.RED); return textView; } }然后你用uni.requireNativePlugin(插件名)的方式拿到的就不再是一个纯逻辑对象而是能在页面上直接渲染的组件了。组件插件在调试时比 Module 插件更麻烦因为你要同时关注 JS 层渲染和原生生命周期建议在开始之前先啃一遍官方 demo 里的“Component 扩展”示例代码不要直接从文档跳进代码。5.2 BLE 蓝牙、扫码、定位系统能力类插件的最佳实践搜索热词里频繁出现的“uni-app ble ios 可以根据蓝牙的 deviceid 建立连接吗”说明很多团队在做物联网类的 App。这类需求的天然痛点在于uni-app 内置的蓝牙 API 在 iOS 和 Android 上的行为不一致且低功耗蓝牙在大数据包传输时容易出问题。我之前在一个冷链监控项目里做过一款 BLE 插件给团队定下的实践原则有三条所有扫描、连接、收发数据的核心逻辑全部由原生实现JS 层只负责传参和收回调。蓝牙状态变化、连接断开等事件通过UniSDKInstance.fireEvent主动推给 JS 层而不是 JS 层轮询去查。考虑到 Android 不同机型对 BLE 协议栈的实现差异扫描和连接都做超时保护与重试机制。系统能力类插件有一个通用陷阱权限声明和运行时权限申请。从 Android 11 开始蓝牙相关权限开始收紧到 Android 12 更是引入了BLUETOOTH_SCAN、BLUETOOTH_CONNECT等新运行时权限。如果你的插件没有处理好运行时权限的申请流程在较新的机型上会直接没有扫描结果。这里建议配备一个“权限申请工具类”放在插件内部在首次调用蓝牙功能时自动请求权限而不是依赖 JS 层先去判断和申请。因为权限弹窗必须要由原生 Activity 发起JS 层只能调uni.authorize这种 H5 风格接口效果不够稳定。5.3 对接第三方 SDKjar 包、aar 包和资源文件的合并在实际项目中你写的插件往往不是“从零开始”而是“把一个已经存在的 SDK 包装成 uni-app 能调用的插件”。这里有几个经验分享如果第三方 SDK 只有 jar 包直接放进插件模块的libs目录记得在build.gradle中加上implementation fileTree(dir: libs, include: [*.jar])。如果第三方 SDK 是 aar 包同样放进libs目录但要额外加一行依赖implementation fileTree(dir: libs, include: [*.aar])。如果 SDK 里包含资源文件比如内置 UI、图片、布局建议用 aar 方式集成因为 aar 里可以包含 res而 jar 包不行。如果 SDK 需要在AndroidManifest.xml里注册 Activity、Service 或 ContentProvider你需要把这些声明合并到插件的AndroidManifest.xml中注意冲突的权限名、provider 的 authorities 需要改成自己应用的包名。最后一条经常被人忽略。很多 SDK 会在 manifest 中注册一个ContentProvider比如用来做初始化数据上报的然后你在集成时会遇到 “Provider conflict” 或 “authority 重复” 的报错这时候tools:replaceandroid:authorities加在application节点上方并且把 authorities 改成你应用的包名 后缀。5.4 需要注意的一个现实问题iOS 端的插件机制差异虽然这个标题限定在安卓但在实际业务中难免会被问到“iOS 能不能用同一份插件”。这里统一说明一下uni-app不支持跨端复用同一套原生代码iOS 使用 Objective-C 或 Swift 开发独立的插件。iOS 有独立的插件协议需要在 Xcode 工程中开发HBuilderX 会调用它。如果你只是一个小团队不打算两端都各养一个原生开发那我建议你在技术选型阶段充分评估“使用 uni-app 内置 API 还是自定义插件”的平衡尽量避免在 iOS 端也要写原生的局面。如果确实躲不掉至少保证 Android 端的插件架构设计合理后期把 iOS 插件移植过去时JS 层接口保持一致即可。6. 真机调试与 Android Studio 配置现场排错实录环境搭好了插件也写了本地打包也能跑了但这只是热身。真正的开发时间里有 60% 会花在“修问题”上。这里挑三个我最有代表性的排错过程复盘一下思路。6.1 日志看不见我怎么定位插件问题写插件调试最痛苦的其实是日志问题。HBuilderX 的 Console 输出的是 JS 日志原生代码里的Log.d需要你用 ADB 命令去看adb logcat | grep -E UniPlugin|your.package.name建议在插件代码里打日志时统一加一个TAG格式用UniPlugin-模块名方便过滤private static final String TAG UniPlugin-DeviceInfo; Log.d(TAG, getDeviceId: androidId androidId);另外一个隐蔽的坑是真机运行模式下HBuilderX 的调试器自带的 console 日志只能捕获 JS 层原生层 print 的堆栈不会出现在里面所以如果你只盯着 HBuilderX 的 Console 找问题很容易漏掉原生层的异常。用 Android Studio 直接连手机看 Logcat 是最佳方案遇到崩溃还能看AndroidRuntime的堆栈。6.2 一个崩溃排查类找不到到底是谁的锅有一次我在集成某个 map SDK 时遇到的报错是java.lang.NoClassDefFoundError: com/xxx/sdk/core/InitCallback。这种错误通常有四种原因缺少对应依赖最常见检查build.gradle里有没有引全。依赖冲突两个 aar 中的同一个类版本不一致。查找办法是执行gradle :app:dependencies并观察输出。插件模块没有被正确“合并”到壳工程中。如果你用了 HBuilderX 的本地插件配置但壳工程里的libs目录没有对应 aar构建时不会报错但运行时会类找不到。混淆导致。release 包打包时如果你开启了混淆规则minifyEnabled true第三方 SDK 的keep规则可能没有补充全导致 SDK 内部类被裁剪或改名。我那次排查到最后发现是第四个原因解决方案是在主模块的proguard-rules.pro中加了几行 keep 规则。建议你从一开始就保持第三方 SDK 的 keep 规则独立放在插件模块自己的proguard-rules.pro中这样换项目时不用重复踩坑。6.3 打包加固后签名失效教你一套完整重签流程热词里那一条“uni-app 开发的 app 加固后如何重新签名”非常真实。项目上架前要做应用加固很多加固平台会用自带的签名工具先对 APK 做二次签名如果你在加固后直接安装就会报“签名不一致”的错误。这里的标准流程是先对原始 APK 用正式签名文件进行一次签名。然后上传加固平台进行加固加固产物通常是一个未签名的 APK有些平台会保留META-INF签名块有些不会。用apksigner对加固后的 APK 进行重签名。关键参数如下apksigner sign --ks your-keystore.jks --ks-key-alias your-alias --ks-pass pass:your-password --out signed.apk unsigned.apk签完后再用apksigner verify --print-certs signed.apk检查证书和原始证书是否一致。这个命令是你验证整个流程有没有问题的最快方式。另外提一句如果你的 APP 用到了微信登录、支付宝支付这类需要签名校验的 SDK更换签名后必须在对应开放平台重新配置新的签名值否则登录支付会直接失败。这个我在项目上线前吃过亏重新签名后微信登录一直回调失败排查了整整两天才想起微信开放平台上的应用签名还是旧的。7. 插件写完了怎么做好后续迭代和维护写完插件只是开始真正的坑往往在后续迭代中暴露。根据我的经验插件维护主要关注下面几个方面。7.1 版本管理原生插件也要搞版本号体系很多团队把原生插件当成“一次性代码”改完就扔等项目升级时发现插件和最新 uni-app 引擎不兼容只能重新找人看代码时间全浪费在“回忆”上。我的做法是每个原生插件从第一天起就纳入版本管理版本号遵循语义化版本规范package.json中的version字段每次改动都要递增。每次 HBuilderX 或离线 SDK 升级时专门安排一次“兼容性验证”验证内容包括构建是否通过、插件能否正常加载、核心功能是否正常。这些验证结论记录在插件的CHANGELOG.md里方便之后回溯。7.2 离线 SDK 升级后插件报错先检查这三点uni-app 的引擎一直在迭代离线 SDK 一旦升级插件可能面临 API 变化风险。升级后如果插件报错我建议按这个顺序检查检查依赖版本离线 SDK 自带的uniapp-release.aar版本是否和你插件里compileOnly的版本一致。不一致就更新。检查 API 兼容性看插件用到的UniModule、UniJSCallback、UniSDKInstance等类是否有方法被标记Deprecated或者签名有变化。检查编译配置新版离线 SDK 对compileSdkVersion、targetSdkVersion、AGP 版本可能有更高要求按升级日志逐条核对。如果项目时间紧、没有精力适配新版本也可以暂时保持旧版 SDK 不动只要你的 HBuilderX 版本能同时兼容本地插件的构建即可。但长期看“升级一次、验证一次”是绕不过去的。7.3 插件的接口设计是一门学问写原生插件的人有两种极端一种是把所有逻辑全部塞给 JS 层原生只是传声筒另一种是把所有逻辑都放在原生JS 层调用时传一堆复杂参数。两种都不健康。我推荐的设计原则是原生层负责“能力”JS 层负责“策略”。原生层暴露最小粒度的功能接口比如connectDevice(params)、sendData(bytes)、disconnect()至于这些接口怎么组合成业务逻辑、什么时候重试、要不要提示用户都由 JS 层决定。这样做的好处是插件职责单一且 JS 层改动不需要重新打包迭代效率高很多。缺点当然也有JS 层要处理更多异步状态管理但那本来就是 JS 工程师的强项。在接口层面所有回调结果建议统一采用{ code, data, message }三段式结构。code 为 0 表示成功非 0 表示失败message 给一个方便排查的错误描述。这能极大减少前后端联调时的沟通成本。8. 上线前必须过的五道检查少一道都可能被拒最后补充关于上架相关的实操经验。很多团队的 App 因为原生插件里藏了问题在上架审核时被驳回或者上线后崩溃率高被警告下架。以下检查项建议在每次发版前执行一遍。第一道权限检查。只申请你实际用到的权限。有一些第三方 SDK 会默认申请一堆权限如果你的插件直接依赖了这些 SDK在隐私政策里必须一一列明。比如申请了定位权限但 UI 上没有位置功能很容易被市场审核盯上。第二道混淆规则。如果你在 release 包中启用了混淆务必为插件相关的所有类添加 keep 规则。否则上线后可能会出现用户点击某个功能时闪退但你自己测试时却完全正常的情况。第三道多机型适配。安卓碎片化是老生常谈但每次都会被低估。我一般会在以下设备上做核心功能回归一台 Android 8 或 9 的低端机、一台主流的 Android 12 或 13 中端机、一台最新的折叠屏或大屏设备。重点观察插件渲染的 View、回调时序、崩溃率。第四道冷启动与后台恢复。如果插件中有需要初始化的操作要确保 App 冷启动、从后台被系统回收后恢复到前台时插件都处于可用状态。如果插件内部缓存了Context或Activity引用在 Activity 销毁后继续使用会引发内存泄漏或空指针。第五道隐私合规。如果你在插件中读取了设备标识如 IMEI、Android ID从 Android 10 开始这些标识的获取会受到严格限制。现在主流应用市场都要求隐私政策中明确说明收集了哪些设备信息、用途是什么。建议尽量使用官方推荐的广告标识符OAID替代旧的设备标识。强烈建议把以上五道检查项写成一份 checklist 文档放在仓库里每个版本发布前由技术负责人逐项打勾。别嫌麻烦我见过太多因为权限或隐私问题被应用市场连续驳回的团队最后补材料补得焦头烂额。写在最后一个实际项目后的个人经验总结如果你第一次接触 uni-app 原生插件开发这套流程走下来可能要花上两三天时间中间大概率会遇到版本不匹配、回调线程、依赖冲突之类的问题。但一旦你打通了一条完整的链路会发现后面的开发速度飞快。我现在做一个普通的 Module 插件从建工程到真机跑通基本上一个下午就能搞定复杂一点的也就一两天。最后再分享一个小技巧在你的插件仓库里同时维护一个“minimal demo”页面专门用来测试插件的所有接口。页面里只放一个按钮和一个 textarea点击按钮调用一个接口把回调结果显示在 textarea 里。这样做的好处有两个——第一每次升级插件后你可以在真机上快速回归不需要打开完整业务 App第二当你需要向同事或外部开发者演示插件能力时这个 demo 页面是最直观的“说明书”。原生插件开发这件事看着门槛高真正跨过去以后你会发现它反而是 uni-app 整个技术栈里最稳定、最值得投资的一块。因为它把你的能力边界从“前端框架的开放能力”一下子扩大到了“安卓系统的所有能力”这种边界拓展带来的项目自由度是纯前端方案给不了你的。到那时候你再回头看最开始想“要不砍掉这个功能”的时刻会很庆幸自己选择了把这条路走通。