做了几年uni-app项目从Vue2一路用到Vue3从H5做到App再到小程序我最大的感受就是uni-app的多端覆盖能力确实能打但碰上硬件交互、系统级能力、第三方SDK这类需求时JS层往往不够用。市面上的原生插件市场虽然有不少现成方案可一旦遇到定制化需求——比如对接公司自研硬件、读取特定传感器数据、或者要绕过某些SDK的版本限制——就只能自己写原生安卓插件。这篇文章想分享的就是我踩过无数坑之后整理出来的一条相对顺畅的uniapp原生安卓插件开发路径从环境搭建、工程结构、编码实现到调试联调和最终打包上架尽量把关键环节和容易翻车的地方都讲透。不管你是刚接触插件开发、被UniModuleUniComponent这些概念绕晕的新手还是已经写过几个插件但总在调试和打包环节卡壳的老手这篇内容应该都能给你一些参考。1. 为什么uniapp项目会走到原生插件这一步1.1 多端复用的边界在哪里很多团队选uni-app就是因为一套代码多端运行这确实省了不少人力。但有个现实问题必须认清uni-app的JS层能力是各端能力集的交集不是并集。比如在H5端可以轻松调用的navigator.geolocation在App端要走uni.getLocation而uni.getLocation能拿到的定位精度在部分安卓机型上又不如原生LocationManager直接调用。再比如蓝牙操作uni.openBluetoothAdapter这类API在多数场景下够用但一旦涉及低功耗蓝牙的MTU设置、自定义广播包解析、或者多设备并发连接JS层的API就不够灵活了。这些场景就是原生插件的用武之地。原生插件本质上是把安卓/iOS的SDK能力封装成uni-app可以调用的模块它运行在原生层不受JS引擎限制可以调用任何系统API、任何第三方SDK然后通过回调把结果传回JS层。1.2 什么情况下必须写原生插件我归纳了几类典型场景符合其中任意一条你就该考虑原生插件而不是继续在JS层做文章系统级能力调用获取WiFi列表、读取SIM卡信息、访问剪贴板历史、监听通知栏、系统级悬浮窗等这些能力普遍涉及敏感权限或系统APIuni前缀的API覆盖不了。第三方SDK的深度集成像人脸识别、活体检测、安全键盘这类SDK官方插件市场虽然有几个封装版本但往往版本滞后、定制能力差出问题还不好排查。性能敏感的原生UI组件长列表渲染、实时视频处理、复杂动画等场景用原生View实现远比H5渲染流畅这就需要写UniComponent类型的组件插件。已有原生代码的复用团队之前做过原生安卓应用有现成的功能模块与其在uni-app里重新实现一遍不如直接搞成插件接入。1.3 原生插件和renderjs、web-view的取舍在决定写原生插件之前还有两个相对轻量的方案值得对比很多人容易在这里走弯路。renderjs适合在App端运行一些需要操作DOM或调用部分web API的逻辑它运行在webview的JS环境中能访问部分plus API但能力边界依然受限。如果你只是想在App端跑一段复杂的前端计算逻辑renderjs是完全够用的没必要上原生插件。web-view适合把已有的H5页面嵌进去如果你的原生能力可以通过H5页面间接实现比如通过URL Scheme调起App、通过JSBridge和App通信那也可以先考虑web-view方案。但web-view的通信成本高、体验打折、部分系统能力依然拿不到。这三者的对比我做了一张表方便你快速判断方案实现难度能力边界性能表现适合场景renderjs低弱受webview限制中等纯前端计算逻辑、DOM操作web-view低中等依赖H5能力较低已有H5页面复用、快速集成原生插件高强任意系统能力高硬件交互、系统级API、深度SDK集成2. 动手前的准备工具链、工程结构与选型2.1 开发工具链清单写原生安卓插件开发环境是绕不开的第一道门槛。你需要准备的东西不算多但版本一定要对齐否则Gradle同步那一关就够你折腾半天的。我目前使用的环境版本如下仅供参考不要求完全一致但大版本建议保持一致Android Studio推荐使用最新稳定版至少确保能创建和编译Android项目。JDK优先用JDK 17Android Studio自带JBR也可以个别老项目可能需要JDK 8或11这个取决于你最终要适配的安卓SDK版本。Gradle建议7.4以上Android Gradle Plugin版本建议7.0以上这两个版本组合如果低于某个阈值可能无法正常编译现代安卓项目。HBuilderX使用3.x以上版本我开发时用的是3.8不同版本的HBuilderX对插件包的规范略有差异尤其是package.json的配置低版本可能不认integrateType字段。真机设备一定要准备一台安卓真机模拟器会遇到非常多兼容性问题比如蓝牙、NFC、传感器等硬件能力在模拟器上基本不可用。提示不要用安卓模拟器做原生插件的核心功能调试很多系统API在模拟器上是假实现你在模拟器上跑通了真机反而报错让你误判问题方向。2.2 认识uniapp原生插件的两类形态uni-app原生插件分为两种类型理解他们的区别是后续开发的基础Module模块这是一种无UI的原生能力封装JS层通过uni.requireNativePlugin(插件名称)获取到模块对象然后调用其方法方法执行完通过回调把结果返回JS层。适合封装工具类能力、SDK调用、数据计算等场景。Component组件这是一种原生UI组件可以直接在vue页面中使用像xxx-view这种标签一样使用组件内部用原生View渲染。适合列表组件、播放器、图表、扫码等需要原生渲染的UI场景。这里有个容易混淆的点Module和Component的返回值方式不同。Module的方法可以通过回调异步返回数据也可以通过返回值同步返回而Component的数据交互更多依赖事件$emit和属性绑定props。在实际项目中如果你的功能既有UI展示又有逻辑处理往往需要同时写一个Module和一个Component配合使用。2.3 工程结构本地插件还是云端插件uni-app的插件开发过程中你可以先把插件作为本地插件放在项目里调试调试通过后再上传到插件市场或者用于云打包。这个环节的规划直接影响后面的开发效率。一个典型的本地插件目录结构如下nativeplugins/ └── WifiModule/ ├── android/ │ ├── src/ │ │ └── com/example/uniapp/wifi/ │ │ └── WifiModule.java │ ├── libs/ │ │ └── xxx-sdk.aar │ └── build.gradle ├── ios/ │ └── (iOS相关文件) └── package.json在manifest.json的App原生插件配置里勾选本地插件选择WifiModule目录HBuilderX运行到真机时就会自动编译并打包成一个自定义调试基座。本地插件和云端插件有个关键区别本地插件只用于自定义调试基座联调不能直接用于正式打包除非你使用离线打包方案。也就是说你的插件开发调试阶段可以通过本地插件快速迭代但最终要发布版本时要么把插件上传到DCloud插件市场后再云打包要么走离线打包流程把插件aar直接集成到安卓工程中。3. 写一个能用的原生插件以WiFi扫描为例理论讲再多不如实际写一个插件。我拿获取WiFi列表这个需求来完整演示一遍Module插件的开发过程因为这个场景几乎涵盖了原生插件开发的所有关键点权限申请、线程切换、异步回调、JSON数据组装。3.1 创建插件类UniModule在Android Studio中新建一个ModuleLibrary然后在其中创建一个Java类继承UniModulepackage com.example.uniapp.wifi; import android.content.Context; import android.net.wifi.ScanResult; import android.net.wifi.WifiManager; import com.alibaba.fastjson.JSONArray; import com.alibaba.fastjson.JSONObject; import io.dcloud.feature.uniapp.annotation.UniJSMethod; import io.dcloud.feature.uniapp.bridge.UniJSCallback; import io.dcloud.feature.uniapp.common.UniModule; public class WifiModule extends UniModule { private WifiManager wifiManager; Override public void onCreate() { super.onCreate(); Context context mUniSDKInstance.getContext(); if (context ! null) { wifiManager (WifiManager) context.getApplicationContext() .getSystemService(Context.WIFI_SERVICE); } } UniJSMethod(uiThread false) public void getWifiList(JSONObject options, UniJSCallback callback) { // 这里先省略核心逻辑后续补充 } }几个容易忽略的细节类的包名和类名非常重要后面package.json里的class字段必须和这里完全一致包含完整包名否则插件找不到。重写onCreate方法做初始化是推荐做法mUniSDKInstance.getContext()获取的是当前uni-app实例的上下文可能为null所以要做空判断。UniJSMethod注解里的uiThread参数控制方法是否在主线程执行。默认是true所以耗时操作记得显式声明为uiThread false否则你直接在主线程里做耗时操作会卡死UI甚至触发ANR。3.2 核心逻辑权限申请与扫描调用WiFi扫描在安卓上涉及权限和位置服务两个前置条件这里正好演示原生插件如何处理动态权限UniJSMethod(uiThread false) public void getWifiList(JSONObject options, UniJSCallback callback) { if (callback null) return; // 回调对象要捕获因为权限回调是异步的 this.wifiCallback callback; if (wifiManager null) { this.wifiCallback null; JSONObject err new JSONObject(); err.put(code, -1); err.put(message, WifiManager is null); callback.invoke(err); return; } // 检查并申请权限 if (!checkAndRequestPermission()) { return; // 权限回调后再继续 } // 发起扫描 boolean started wifiManager.startScan(); if (!started) { JSONObject err new JSONObject(); err.put(code, -2); err.put(message, startScan failed); callback.invoke(err); return; } // 扫描是异步的需要延时一段时间后读取结果 new Handler(Looper.getMainLooper()).postDelayed(new Runnable() { Override public void run() { ListScanResult results wifiManager.getScanResults(); JSONArray arr new JSONArray(); for (ScanResult result : results) { JSONObject item new JSONObject(); item.put(ssid, result.SSID); item.put(bssid, result.BSSID); item.put(level, result.level); item.put(frequency, result.frequency); arr.add(item); } JSONObject success new JSONObject(); success.put(code, 0); success.put(data, arr); callback.invoke(success); } }, 2000); }这里有个很关键的时序问题startScan()之后不能立刻读取getScanResults()因为系统扫描WiFi是个异步过程通常需要1到3秒才有结果。我用了Handler.postDelayed延时2秒读取这只是个简化的示例。实际生产中更稳妥的做法是注册BroadcastReceiver监听WifiManager.SCAN_RESULTS_AVAILABLE_ACTION广播扫描完成时再读取结果。3.3 权限申请的正确形态在安卓6.0API 23以上涉及危险权限的动态申请必须出现在插件代码中。很多新手在这里栽跟头以为Manifest里声明了权限就够了运行时照样被拒绝。需要在插件里主动requestPermissionsprivate static final int REQUEST_CODE_WIFI 1001; private boolean checkAndRequestPermission() { Context context mUniSDKInstance.getContext(); if (context null) return false; if (android.os.Build.VERSION.SDK_INT 33) { // Android 13 新增 NEARBY_WIFI_DEVICES 权限需要单独申请 if (context.checkSelfPermission(android.permission.NEARBY_WIFI_DEVICES) ! PackageManager.PERMISSION_GRANTED) { requestPermissions(new String[]{ android.permission.NEARBY_WIFI_DEVICES }, REQUEST_CODE_WIFI); return false; } } if (context.checkSelfPermission(android.permission.ACCESS_FINE_LOCATION) ! PackageManager.PERMISSION_GRANTED) { requestPermissions(new String[]{ android.permission.ACCESS_FINE_LOCATION, android.permission.ACCESS_COARSE_LOCATION }, REQUEST_CODE_WIFI); return false; } return true; } Override public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (requestCode REQUEST_CODE_WIFI) { boolean allGranted true; for (int result : grantResults) { if (result ! PackageManager.PERMISSION_GRANTED) { allGranted false; break; } } if (allGranted) { // 权限通过重新执行扫描 getWifiList(null, wifiCallback); } else { JSONObject err new JSONObject(); err.put(code, -3); err.put(message, permission denied); if (wifiCallback ! null) { wifiCallback.invoke(err); } } } }这里要特别注意onRequestPermissionsResult是异步回调所以必须把原始的回调对象wifiCallback保存为成员变量权限通过后再重新调用getWifiList或继续执行后续逻辑。如果直接把这个回调弄丢了JS端就永远等不到数据返回。安卓13API 33之后WiFi相关权限有变化新增了NEARBY_WIFI_DEVICES权限而且它是仅一次式的运行时权限需要做版本判断这也是很多旧插件在高版本安卓上闪退的常见原因。3.4 package.json与aar打包插件代码写完后需要把Android工程打包成aar文件同时在插件目录下编写package.json描述文件。aar打包方式在Android Studio的Gradle面板中找到library模块的assembleRelease任务执行后在build/outputs/aar/目录下找到生成的aar文件拷贝到插件目录的android/libs/下。package.json是插件的身份证HBuilderX识别插件全靠它{ name: WifiModule, id: WifiModule, version: 1.0.0, _dp_type: nativeplugin, _dp_nativeplugin: { android: { plugins: [ { type: module, name: WifiModule, class: com.example.uniapp.wifi.WifiModule } ], integrateType: aar, minSdkVersion: 21, dependencies: [ com.alibaba:fastjson:1.2.83 ], abis: [armeabi-v7a, arm64-v8a] } } }几个字段的含义容易踩坑我具体说明一下integrateType固定填aar代表插件以aar形式集成。如果是源码集成可以填source但源码方式对工程侵入大不推荐。如果填错云打包阶段就会报错还很难查。plugins数组里type有module和component两种对应前面说的两类插件形态。多个插件可以共用一个aar比如你打包了一个包含多个模块的aar然后在plugins数组里声明多个条目。abis如果插件里有so库这里必须声明支持的ABI架构。如果声明了armeabi-v7a但实际aar里没有对应的so运行时就会报UnsatisfiedLinkError。如果不涉及so库可以留空数组或直接删掉这个字段。3.5 在uni-app端的调用方式插件开发完成后前端调用方式非常简单template view button clickscanWifi扫描WiFi/button view v-foritem in wifiList :keyitem.bssid {{item.ssid}} - 信号强度: {{item.level}} /view /view /template script export default { data() { return { wifiList: [] }; }, methods: { scanWifi() { const wifiModule uni.requireNativePlugin(WifiModule); wifiModule.getWifiList({}, result { console.log(scanWifi result:, JSON.stringify(result)); if (result.code 0) { this.wifiList result.data; } else { uni.showToast({ title: result.message || 扫描失败, icon: none }); } }); } } }; /script这里uni.requireNativePlugin(WifiModule)里的名字必须和package.json里的id字段完全一致。如果调不到模块或者提示无法找到插件优先检查这个id是否匹配这是最高频的错误之一。4. 联调路上的高频坑日志与报错排查插件写好了但联调的时候才是真正的修罗场。HBuilderX和原生环境之间的报错不像纯前端那样直观很多问题都是模棱两可的。我把自己踩过的几个高频坑整理出来帮你节省排查时间。4.1 自定义调试基座的制作与使用本地插件联调之前先要做一次自定义调试基座。在HBuilderX中操作路径是运行→运行到手机或模拟器→制作自定义调试基座。制作完成后再次运行到手机时选择自定义调试基座这样App才会把nativeplugins目录下的插件一起打包进去。这个环节有两个高频问题基座没有重新制作你改了插件代码、加了新权限但运行用的还是老基座自然看不到任何新效果。这个问题非常容易忽略尤其是你只是改了插件的Java代码前端代码改了会自动热更新但原生代码修改必须重新制作基座。基座包名冲突自定义基座的包名是io.dcloud.HBuilder如果手机上一个同包名的App已经安装会导致安装失败。解决办法是卸载旧包再重新运行。4.2 日志排查logcat是救命稻草前端报错在HBuilderX的控制台能看到但原生层的异常、崩溃日志控制台不一定完整展示。这时候就要靠logcat了。你可以先在Android Studio中打开Logcat面板SQLite日志过滤一般选择过滤当前进程也可以通过关键词过滤例如你的插件tag、类名、UniModule等。一个排查实例某次我封装了一个NFC读取插件真机运行后点击按钮无任何反应前端也没有报错。用logcat过滤后发现如下日志DCloudUniApp: UniModule-WifiNfcModule is not found这个日志说明插件根本没有被加载。排查过程检查package.json的id是否与uni.requireNativePlugin里的参数一致。确认插件包是否放在nativeplugins目录下、目录名是否与id相同。检查package.json里plugins[0].class的包名是否写错或者类是否被混淆了。最终发现是我在Gradle里开了混淆插件类名被改名了。安卓打包时要给插件目录加consumerProguardFiles并配置keep规则或者直接在library的build.gradle里关闭minifyEnabled。4.3 方法回调不触发的经典原因插件方法明明写了callback.invoke()但前端就是收不到回调这是Module插件开发里最常见的Bug。根据经验按以下顺序排查回调对象被释放如果你把UniJSCallback存储为成员变量而onDestroy时没有正确处理可能导致回调失效。线程问题如果在子线程直接invoke而模块是uiThread true可能出现时序问题。最稳妥的做法是切到主线程再invokemUniSDKInstance.getContext().runOnUiThread(new Runnable() { Override public void run() { callback.invoke(result); } });多次调用invokeUniJSCallback的invoke方法调用一次可以正常通知前端。第二次调用会覆盖第一次的消息但在复杂逻辑中容易造成前端无从判断。如果需要多次回调比如进度事件要使用invokeAndKeepAlive方法。invoke和invokeAndKeepAlive的区别很关键invoke调用后回调会被释放适合一次性返回结果invokeAndKeepAlive调用后回调依然存活可以继续回调多次适合进度上报、状态监听等场景。4.4 编译期报错与so库冲突如果你在插件中引用了第三方aar编译和运行阶段可能的报错样式非常多。这里举几个最常见的依赖冲突插件依赖了一个版本的support-annotations或androidx.core而uni-app SDK也依赖了同一个库的不同版本编译时就会出现重复类或版本冲突。解决办法是在自己模块的build.gradle里使用exclude移除冲突的传递依赖或者升级到统一版本。so库冲突插件里带了armeabi-v7a的so但uni-app基座本身只保留arm64-v8a导致在部分机型上崩溃。解决办法是确保插件的so目录结构完整libs/armeabi-v7a、libs/arm64-v8a缺一不可进一步也可以通过abiFilters统一指定。构建缓存导致的老代码Gradle的缓存机制有时候非常顽固。插件代码改了重新打包但运行后行为还是旧的。这时候试试Android Studio的Build→Clean Project以及File→Invalidate Caches / Restart然后重新构建。看起来像是玄学但确实能解决不少诡异问题。5. 打包、版本与协作插件交付的最后一公里插件联调通过只是第一步最终要让插件真正跑在用户的正式包里需要处理好打包、版本管理和团队协作几个问题。5.1 云打包还是离线打包正式打包有两条路选哪条取决于你的具体需求云打包通过HBuilderX上传代码到DCloud云端服务器进行打包本地不需要安装安卓SDK与Gradle环境。但在使用本地插件时云端打包需要先把插件制作成zip包上传到DCloud插件市场或使用公共插件授权方式流程更繁琐而且插件市场审核有周期。离线打包下载DCloud官方提供的安卓离线打包SDK在本地用Android Studio构建正式包把插件aar一并集成进去。这种方式灵活度高便于后续接入自己的签名、推送、热更新等逻辑但要求本地构建环境稳定。我个人建议如果团队里有原生安卓开发经验优先选离线打包。云打包虽然省事但遇到问题时的排查空间很小——你看不到构建日志也不知道云端Gradle版本是多少出了问题只能猜。离线打包集成插件时要把aar文件放到离线SDK工程的libs目录并在build.gradle中声明依赖同时把package.json里的dependencies声明的第三方依赖一并加入dependencies { implementation fileTree(dir: libs, include: [*.jar, *.aar]) implementation com.alibaba:fastjson:1.2.83 // 其他插件依赖 }5.2 插件版本迭代的注意点插件一旦发出去版本管理就要讲究起来。我在实际项目中吃过不少亏总结三条实用经验版本号与插件id要稳定package.json里的version字段是用户判断是否需要更新的依据但更重要的是id字段不能随意修改。一旦改了id老用户的项目会出现找不到插件的错误。接口兼容性要守住新增方法时不要变动旧方法的签名和回调数据结构。如果非要改建议新增一个方法保留旧方法做兼容前端根据插件版本号调用不同方法。我和前端同事约定了一个惯例回调结果里的code字段0永远代表成功非0代表失败message永远是人类可读的错误描述。这个约定让很多联调问题变得简单。插件更新提醒uni-app插件市场支持设置插件更新日志。即使不发布到市场自己团队内使用建议也在插件的README或代码里维护一份更新日志避免过几个月后根本想不起来这个版本改了什么。5.3 团队协作时的目录与文档规范如果你的团队里前端不会看Java代码原生开发只有你一个人那更要提前定好协作规范。几个建议插件目录放在独立Git仓库不要和uni-app业务代码混在一个仓库里。这样插件可以独立发版业务工程通过git submodule或直接复制aar来引用。package.json里维护好description字段插件有哪些方法、每个方法的参数和回调格式写清楚。很多开源插件的文档都写得惨不忍睹但我发现接口说明文档的质量直接影响前端接入效率。我通常会在package.json旁边放一份API.md每次更新插件都同步更新它。封装一层前端SDK不要让业务代码直接uni.requireNativePlugin到处散落调用。比如我在uni-app项目里会建立utils/wifi.js统一封装// utils/wifi.js const wifiModule uni.requireNativePlugin(WifiModule); export function getWifiList() { return new Promise((resolve, reject) { wifiModule.getWifiList({}, (result) { if (result.code 0) { resolve(result.data); } else { reject(new Error(result.message)); } }); }); }这样业务层永远面对的是Promise风格的API即使后面插件接口变了只需要改这一层封装不用全项目搜调用点。6. 给后来者的几条选型建议最后这部分我根据自己的实际经验针对几个常见问题给出一些方向性的建议希望能帮你在动手前想清楚。6.1 能复用就不要重复造轮子写插件之前先去DCloud插件市场和GitHub上搜一搜有没有现成的。很多人一上来就我要自己写结果写了个半吊子功能比不上现成的维护却要耗费大量时间。说实话插件市场上有些作者更新很勤快比如各种扫码、定位、推送插件与其自己从零写不如基于开源项目做二次封装性价比高得多。但反过来如果你的项目有特殊需求比如定制协议、专有硬件那还是自己写比较稳妥因为别人的插件未必让你改到底层。6.2 优先用Kotlin还是Java官方文档和很多旧教程用的都是Java示例但如果你是从零开始新写插件我更推荐用Kotlin。原因很简单现在的Android生态已经全面转向KotlinGoogle官方库、第三方SDK的新版本几乎都优先支持Kotlin。不过要注意如果用Kotlin写插件library模块也要配置Kotlin插件否则打包出来没法解析Kotlin标准库。如果你是新手连Java都不太熟那就先用Java。插件的核心逻辑其实不复杂Java的样例更多排查问题的时候搜到的资料也更多。等熟悉了再迁Kotlin也不晚。6.3 性能与包体积的取舍插件不是写得越多越好。每个插件都会打进APK里增加包体积和初始化时间。我见过有人把一个简单的取设备信息的逻辑都写成插件结果App启动时长明显增加这个做法有待商榷。如果只是读一些公共信息比如设备型号、系统版本、应用列表等uni.getSystemInfoSync()其实就够用了没必要非上原生插件。原生插件应该用在真正非它不可的地方——系统级能力、高性能UI、第三方SDK封装。6.4 沿着这条路继续扩展原生插件开发并不是一个孤立的技术点它其实是uni-app开发者打通跨端框架原生底层的一个重要入口。一旦你学会了Module插件后续你可以很容易扩展到Component插件捋顺了安卓端的插件流程再去做iOS端插件不过是思路的平移只是语言从Java/Kotlin变成了Objective-C/Swift能调用的系统框架不同而已。我自己的学习路径是先做了一两个Module插件WiFi扫码、蓝牙通信然后尝试做了一个带原生地图标记的Component插件再往后就是把这套能力用在公司自研硬件的数据对接上。每一次实践都对uni-app的底层运行机制理解更深一点也越能体会到跨端只是方便原生才是边界突破边界得靠自己这句话的分量。最后分享一个小习惯我的插件工程里始终保留一个TestPage页面里面列出了所有插件方法的调用入口和参数说明每写一个新方法就顺手在这里加一个测试按钮。这个页面成本很低但联调时非常有用——不管是自己测还是后来同事接手维护都可以一键验证某个方法是否正常不用每次临时写测试代码。希望你也能找到适合自己团队的插件开发节奏顺利走通这条路。