企业官网建设流程全解析

1. 原生插件开发这件事，到底卡在哪

先说个现象。我见过太多团队在uniapp里折腾了几个月，最后栽在原生能力上。明明JS层写得飞起，一到调用系统摄像头、后台定位、息屏播报这些场景就束手无策。社区里翻来覆去就那几个回答：“去写原生插件吧”“这个只能做原生”。然后呢？没有然后了。

其实uniapp的架构逻辑很简单，它本身是个跨端框架，JS引擎跑业务逻辑，遇到系统能力就通过桥层调原生。问题在于，框架封装的API覆盖不了所有场景。uni.scanCode能扫码，但你要自定义扫码界面加个闪光灯切换，就得碰原生；uni.startLocation能定位，但你要App退到后台还在持续上报位置，就得写原生插件；iOS上你要息屏播报，锁屏状态下继续朗读内容，这更是纯原生的事。

所以原生插件开发是绕不开的坎，尤其做App端。如果你只做小程序，那原生插件的概念基本可以忽略，但做App、做iOS/Android双端，原生插件就是基本功。

这篇文章就是把我自己踩过的坑、趟出来的路梳理一遍。从设计思路到实际操作，从Android到iOS，从后台定位到自动截屏，结合我实际开发过的场景，尽量说人话，给能直接用的方案。

2. 先搞清楚架构：插件不是你想的那样

2.1 原生插件的本质是一层桥

很多人一听“原生插件”就发怵，觉得得精通Java/Kotlin、Objective-C/Swift才能碰。说实话，门槛没你想得那么高。uniapp的原生插件，本质上就是在原生层写一个类，注册给JS层调用。JS调uni.requireNativePlugin('ModuleName')，拿到插件实例，然后调方法、传参数、收回调。

以Android为例，uniapp的插件机制基于它自己的SDK。你需要继承UniModule或者实现UniModule接口，然后在方法上标@UniJSMethod注解。就这么简单。方法里面的实现逻辑，才是你Java/Kotlin功底发挥作用的地方。

public class MyLocationModule extends UniModule { @UniJSMethod(uiThread = false) public void startMonitor(JSONObject options, UniJSCallback callback) { // 这里写原生逻辑 } }

iOS端稍微不一样，uniapp在iOS上用的是UniPluginProtocol协议，你需要创建一个继承NSObject的类，遵循这个协议，然后用WXModuleMethod之类的方式暴露方法。整体思路一致，只是语言和框架细节不同。

2.2 你真正需要的“原生能力”长什么样

我给原生插件开发按需求场景分了个类，方便你对号入座：

• 框架没封装但有现成系统API的场景：比如后台定位、前台服务、息屏播报、自动截屏、相册授权、消息推送集成
• 框架封装了但不够灵活的场景：比如自定义扫码、自定义分享、自定义视频播放器
• 纯原生性能要求的场景：比如大数据量计算、图像处理、音视频编解码

这里要特别提醒一点：不要所有功能都往原生插件里塞。uniapp的优势在于跨端和快速迭代，你业务逻辑写原生，等于自废武功。原生插件只放那些“不得不原生”的部分，能JS解决的就JS解决。

2.3 社区里常见的误区

我发现很多人对uniapp原生插件有一个误解，以为插件市场里买一个、下载一个，就能解决所有问题。插件市场确实有不少成熟方案，但坑也很多。比如插件只适配了特定基座版本，你的自定义基座一升级就崩；比如插件作者只适配了Android没适配iOS；比如插件内部写死了业务逻辑，你要定制就得改源码，但很多付费插件不给源码。

所以我的建议是：能用官方插件用官方插件，用不了就自己写。自己写虽然要啃原生代码，但主动权在自己手里，出了问题能排查，不会两眼一抹黑。

3. Android端原生插件开发实操

3.1 环境准备：本地Android工程才是正道

网上很多教程说用Android Studio直接打开uniapp官方提供的插件模板工程。但我实际用下来的感受是，这个模板工程版本更新频繁，跟你的本地SDK版本容易对不上。更稳的做法是，自己创建一个标准Android工程，然后引入uniapp的SDK依赖。

这里有个核心知识点：uniapp的离线打包SDK。你去DCloud官网下载最新的离线打包SDK，里面包含uniapp-release.aar和uniapp-v8-release.aar这类文件。把这些aar放进你的Android工程的libs目录，然后在build.gradle里配置依赖。

dependencies { implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar']) implementation 'androidx.appcompat:appcompat:1.3.1' implementation 'com.alibaba:fastjson:1.2.83' // 其他依赖 }

注意，uniapp的SDK对Java版本有要求，我用的Android Studio版本是2023.1.1，JDK配置的17，Gradle版本8.0以上，这些问题网上都有对应文档，照着配就行。

3.2 从零写一个后台定位插件

后台定位是我做过的原生插件里最典型的场景。plus.geolocation.watchPosition在App退到后台以后，经常被系统挂起，定位频率越来越低甚至完全停止。这时候就需要原生层启动一个前台服务来保活定位。

思路是在原生层创建一个Service，里面注册LocationManager监听，通过Notification让服务变成前台服务。这样App退到后台，定位服务依然能跑。

public class LocationService extends Service { private LocationManager locationManager; private String provider = LocationManager.GPS_PROVIDER; @Override public int onStartCommand(Intent intent, int flags, int startId) { startForeground(1, createNotification()); startLocation(); return START_STICKY; } private void startLocation() { locationManager = (LocationManager) getSystemService(Context.LOCATION_SERVICE); if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) { locationManager.requestLocationUpdates(provider, 5000, 0, locationListener); } } }

然后在你注册的UniModule里，通过startService拉起这个Service。每次定位结果通过UniJSCallback回调给JS层。

这里有个关键点，@UniJSMethod(uiThread = false)注解一定不能漏。因为定位是耗时操作，如果在UI线程跑，可能会ANR。但回调JS的时候要注意，UniJSCallback只能在UI线程调用，所以你需要用runOnUiThread切回主线程再回调。

3.3 自动截屏插件：权限和兼容性问题

自动截屏这个需求，看起来简单，实际上全是坑。Android上截屏有两种方式：一种是通过MediaProjection，需要用户授权弹窗；一种是root之后直接/system/bin/screencap。做商业App基本选了第一种。

MediaProjection的完整流程很繁琐，大致是：申请MediaProjectionManager，然后通过createScreenCaptureIntent拉起授权弹窗，授权以后拿到MediaProjection，再创建VirtualDisplay，配合ImageReader取帧。

MediaProjectionManager mpm = (MediaProjectionManager) getSystemService(Context.MEDIA_PROJECTION_SERVICE); Intent captureIntent = mpm.createScreenCaptureIntent(); startActivityForResult(captureIntent, REQUEST_CODE);

拿到结果以后，在onActivityResult里读取MediaProjection实例，然后创建虚拟屏幕。

这里要提醒几个容易踩的坑：Android 10以上对MediaProjection的权限管控更严格，需要用户在前台的时候授权，授权以后服务必须保持前台运行，否则系统会回收；ImageReader的格式要用PixelFormat.RGBA_8888，拿到的是原始像素数据，转成Bitmap还得自己处理；部分国产ROM会对后台截屏做限制，华为、小米的系统需要额外引导用户开启“允许后台弹出界面”之类的权限。

3.4 热更新和插件的关系

再聊一个热门话题：热更新。很多人以为热更新能解决所有版本迭代问题。实际上，uniapp的热更新只能更新JS层代码和打包在App里的静态资源。如果你改了原生插件，那就必须重新打包App。

这一点在项目规划时要特别留意。如果你们的原生插件只是偶尔调个系统能力，那热更新够用；但如果你频繁改原生功能，热更新就名存实亡了。我见过最惨的情况是，团队把业务逻辑全写在原生插件里，然后想靠热更新躲过应用商店审核，结果每次改需求都得重新发版，审核周期卡得死死的。

所以原生插件开发的基本原则是：插件方法越原子越好。比如一个定位插件就暴露startMonitor(interval, callback)和stopMonitor(callback)两个方法，业务判断全在JS层。这样原生代码稳定了，JS层才可能通过热更新灵活调整。

3.5 上架安卓应用市场的适配问题

写完插件只是第一步，上架安卓应用市场才是噩梦的开始。国内安卓市场对隐私合规要求越来越严，尤其是定位权限。如果你的App用了后台定位但没在隐私政策里说明，酷安、小米、华为这些渠道都可能驳回。

这个问题必须在插件层面就考虑好。比如定位插件要支持“仅前台定位”和“后台定位”两种模式，由JS层根据业务需求去选择。如果你的应用根本不需要后台定位，就别申请ACCESS_BACKGROUND_LOCATION权限，免得审核被卡。

另外，部分应用市场要求App必须支持64位架构。你在做原生插件的时候，build.gradle里的abiFilters要配置armeabi-v7a和arm64-v8a两种。尤其如果你引用了第三方so库，一定要确认它提供了64位版本，否则上架审核直接不通过。

4. iOS端原生插件开发要点

4.1 iOS插件的基础写法

iOS端的原生插件开发思路跟Android一致，但语言换成Objective-C或Swift。uniapp在iOS上对Swift的支持没那么顺畅，我试过用Swift写插件，某些方法回调会有类型转换问题，后来干脆改用Objective-C。

一个最简单的iOS插件，大致长这样：

#import "UniPlugin.h" @interface MyModule : NSObject <UniPlugin> @end @implementation MyModule - (void)startMonitor:(NSDictionary *)options callback:(UniJSCallback *)callback { // 原生逻辑 if (callback) { [callback invokeWithDict:@{@"status": @"success"}]; } } @end

在UniPlugin的init方法里，你需要用WXModuleManager注册模块，然后JS层才能通过uni.requireNativePlugin找到它。

4.2 息屏播报这个硬骨头

iOS息屏播报的核心难点在于：App退到后台、屏幕锁定以后，系统会休眠，音频播放会被打断。你需要做两件事：一是配置UIBackgroundModes里的audio，二是用AVAudioSession设置播放模式。

AVAudioSession的配置是关键。你必须设置为AVAudioSessionCategoryPlayback，并且调用setActive:error:。这样系统才会允许你的App在后台继续播放音频。

另一个问题是锁屏状态下App的执行时间有限。如果你只是播放固定音频，系统会允许你播完；但如果你要在锁屏状态下做语音合成，比如用AVSpeechSynthesizer播报文字内容，就得用AVAudioSession配合beginBackgroundTask延长后台执行时间。

这段逻辑在uniapp的JS层完全做不了，必须原生实现。我当时的做法是写了一个SpeechModule，暴露speak(text)和stop()两个方法，内部用AVSpeechSynthesizer做合成和播放。这样业务层只需要在JS里调用插件，不用关心后台会话怎么管理。

4.3 iOS的App Store审核注意事项

iOS端最烦的不是写代码，而是审核。你的原生插件如果涉及后台定位、后台音频，都要在App Store的审核备注里写清楚用途。苹果审核团队很较真，你说后台定位是为了“安全追踪”，他就可能会继续追问具体场景。

我踩过一次坑：插件里写了后台音频能力，但App内没有任何显眼的音频功能入口，被审核拒了一次。后来在Info.plist的用途说明里写了详细解释，并在App里加了一个“语音播报”的开关入口，才算过审。

所以iOS原生插件的设计要遵循“显性使用”原则：插件有什么能力，App里就得有对应的可见功能。别写了后台定位却不放定位按钮，别写了息屏播报却不放播报开关，这是被审核毙掉最常见的理由。

5. 从插件到包体：常见问题与排查技巧

5.1 “source size 2612kb exceed max limit 2mb”的解法

这个报错是微信小程序打包时的经典问题。小程序主包大小限制2MB，子包限制各自有额度。你搜一下会发现无数人问，无数人答，但很多答不到点上。

先说结论，这个问题跟原生插件开发的关系不大，但跟uniapp的工程配置强相关。主要原因通常是：静态资源没压缩、图片直接扔在static目录、第三方库体积过大。

实操上，我一般用这几招解决：

• 把图片资源放到云端，本地只保留占位图
• 用optimization配置开启treeShaking，去掉用不到的API
• 用分包加载，pages.json里配置subPackages，把非首屏页面拆进子包
• 检查manifest.json里是否有冗余模块配置

另外有个容易忽略的点：如果你在uniapp项目里引入了uni_modules插件，即使你没用到，某些插件也可能被打进包里。这时候去uni_modules目录检查一下，不用的插件删掉。

5.2 uniapp不打印日志信息怎么排查

这是个很让人抓狂的问题。代码跑了，效果也对，但控制台就是干干净净。没有报错，没有输出，你根本不知道哪里有问题。

绝大多数情况是因为manifest.json里的vue编译配置开了production模式，或者HBuilderX控制台的日志级别被过滤了。还有一个很低级但常见的原因：代码里写的是console.log，但运行环境是App真机，App端的日志得在HBuilderX的“真机运行”面板里看，不是浏览器控制台。

还有一个小概率原因，是原生插件里面打印的日志。Java层用Log.e打的日志，在Android Studio的Logcat里能看见，但不会出现在HBuilderX里。如果你在JS层调用插件后没有任何输出，先怀疑插件方法有没有被正确调用，再怀疑回调有没有触发。

5.3 自定义基座：绕不开的环节

写完原生插件，你不可能每次都在HBuilderX里用标准基座调试，因为标准基座不带你的插件。这时候就要打自定义基座。

流程是：Android Studio里把你写好的插件工程编译成aar，然后放进uniapp离线打包SDK的工程里，再打一个apk作为自定义基座。HBuilderX里配置好自定义基座路径，运行到手机时选择自定义基座。

这里有个容易出错的地方：插件aar里的AndroidManifest.xml和uniapp主工程的AndroidManifest.xml可能有权限冲突。比如你的插件声明了ACCESS_BACKGROUND_LOCATION，主工程也要声明，否则编译报错。用tools:replace属性可以解决冲突，但需要你在Android Studio里手动配置。

5.4 uniapp和uni-appx的区别，到底是什么

最近很多人问uniappx。简单说，uni-appx是DCloud推的下一个跨端框架，用uts语言（TS超集）写逻辑，可以编译到Android、iOS、Web、小程序等端。

但它跟uniapp原生插件开发是两条技术路线。uniappx的编译器能力更强，性能更好，但它目前生态还没那么成熟，第三方插件不如uniapp丰富。如果你现在的项目已经用了uniapp，原生插件方案短期内还是要以uniapp为主。想迁移到uniappx，得等它把原生插件生态补齐了再说。

我个人建议：新项目可以关注uniappx，但现有uniapp项目别轻易迁移。迁移成本远高于收益，除非你遇到了uniapp解决不了的性能瓶颈。

6. 一个完整案例：自定义分享插件的全流程

最后用一个完整的自定义分享插件，把前面的知识点串起来。这个需求很常见：uniapp的uni.share只支持官方渠道，但你要分享到钉钉、企业微信这些非官方渠道，就得写原生插件。

6.1 需求拆解

需求是：JS层传入分享文案和链接，原生层拉起钉钉分享面板。Android端用钉钉SDK，iOS端用钉钉SDK，两端逻辑不同但接口要统一。

我做了一个ShareModule，暴露了三个方法：

• shareToDingTalk(options, callback)：分享到钉钉
• shareToWeCom(options, callback)：分享到企业微信
• isAppInstalled(channel, callback)：判断目标App是否安装

JS层只需要关心channel是dingtalk还是wecom，逻辑全在原生层判断。

6.2 Android端实现

Android端引入钉钉SDK后，在Module里拿到JS传进来的参数，然后调用钉钉SDK的分享接口。分享成功后通过回调通知JS层。

@UniJSMethod(uiThread = true) public void shareToDingTalk(JSONObject options, UniJSCallback callback) { String text = options.optString("text"); String url = options.optString("url"); DDShareMessage message = new DDShareMessage(); message.text = text; message.url = url; // 调用钉钉SDK DingTalkShare.shareMessage(context, message, new DDShareListener() { @Override public void onSuccess() { callback.invoke(makeResult(0, "success")); } @Override public void onError(int code, String msg) { callback.invoke(makeResult(code, msg)); } }); }

注意，调用钉钉SDK的部分必须在UI线程执行，所以uiThread = true必须设置。

6.3 iOS端实现

iOS端使用钉钉的DTApi，流程跟Android类似。需要先在AppDelegate的application:didFinishLaunchingWithOptions里注册DTApi，注册的AppKey在钉钉开放平台申请。

- (void)shareToDingTalk:(NSDictionary *)options callback:(UniJSCallback *)callback { DTShareTextObject *textObj = [[DTShareTextObject alloc] init]; textObj.text = options[@"text"]; DTMediaMessage *message = [[DTMediaMessage alloc] init]; message.mediaObject = textObj; DTApi *api = [DTApi sharedApi]; [api sendReq:message completion:^(DTBaseResp *resp) { if (resp.errCode == 0) { [callback invokeWithDict:@{@"status": @"success"}]; } else { [callback invokeWithDict:@{@"status": @"fail", @"msg": resp.errStr}]; } }]; }

这套代码写下来，JS层调用就很统一了：

const shareModule = uni.requireNativePlugin('ShareModule') shareModule.shareToDingTalk({ text: '这是一条分享文案', url: 'https://example.com' }, (res) => { if (res.status === 'success') { uni.showToast({ title: '分享成功' }) } })

7. 避坑总结：我最后想说的几句话

原生插件开发这件事，技术上不复杂，但细节多、坑多、版本兼容性多。我把几个心得体会放在这里：

第一，别贪多。原生插件只写不得不原生的部分，其他一切放JS层。这样你的插件体积小、逻辑稳定、热更新才能发挥价值。

第二，版本管理要做好。uniapp的SDK、Android的AGP版本、Gradle版本、iOS的Xcode版本，都是牵一发动全身的东西。升级版本之前，先在本地用自定义基座回归一遍所有插件功能。

第三，要想清楚插件和基座的关系。自定义基座能帮你调试，但打包上线用的还是正式包。发布前一定用正式包流程打一遍，别在基座环境里没问题、一发正式包就崩。

第四，社区资料要会看。官方文档写得比较简略，很多细节是在论坛的“踩坑记录”里沉淀的。谷歌搜英文资料、看stackoverflow上的Android原生问题，往往比搜中文问题得到更有效的答案。

原生插件开发说到底，考验的不是你Java或OC写得有多花哨，而是你对跨端架构边界的理解。把JS和原生的边界划清楚，把需要的系统能力准确地暴露出来，这个项目就成功了一半。至于另一半，就是耐心排查和持续踩坑。希望这篇文章能让想碰原生插件的人少走点弯路。