结论:当前主流且推荐的方式是用UTS开发iOS插件,它自动编译为Swift、屏蔽Xcode配置繁琐环节;仅当需封装UIKit组件或集成强依赖原生SDK时,才回归传统Objective-C/Swift插件路径。

直接说结论:现在主流且推荐的方式是用 UTS 开发 iOS 插件,而不是写原生 Objective-C/Swift;但如果你必须对接已有 SDK、需要精细控制生命周期或实现复杂 UI 组件,才需回到传统原生插件路径。
UTS 插件是当前首选,别硬写 OC/Swift
UTS 是 uni-app 官方主推的跨端原生插件开发方式,iOS 上会自动编译为 Swift。它屏蔽了大部分 Xcode 工程配置、头文件引用、Framework 依赖管理等繁琐环节:
- 你只需在
uni_modules/xxx/uts/app-ios/下写.uts文件,定义类、方法、协议实现 - 参数和返回值默认走
Number、String、Array、Object等 UTS 内置类型,平台自动转成对应原生类型 - 遇到三方 SDK 强制要求
Int、CGFloat、UIImage等原生类型时,UTS 允许你显式声明(如a: Int),但仅限协议实现或 delegate 回调场景 - 编译时 HBuilderX 自动为你生成 Swift 源码和 Framework,无需手动建 Xcode 工程、配 Build Settings、处理 BITCODE
⚠️ 容易踩的坑:UTS 不支持直接操作 UIKit 视图树(比如 addSubview)、不支持自定义 UIViewController 生命周期钩子——这类需求必须退回到传统原生插件。
传统原生插件只在必要时用:Component 或强 SDK 依赖
当你需要封装一个原生 UIView 组件(比如地图、视频播放器、AR 视图),或必须集成某个 CocoaPods 库(如 Alamofire、Charts)且其 API 暴露的是 OC/Swift 原生对象时,才用传统方式:
- 插件类必须继承
DCUniPlugin(不是NSObject),否则uni.requireNativePlugin()找不到实例 - 所有暴露给 JS 的方法必须加
UNI_EXPORT_METHOD宏,且参数只能是NSDictionary *,返回值只能是void(同步)或通过callback传回 JSON 兼容对象 - 异步回调必须在主线程外执行耗时逻辑,但最终调用
callback时要切回主线程(dispatch_async(dispatch_get_main_queue(), ^{...})),否则 JS 回调不触发 - 如果用了 CocoaPods,
Podfile中必须加use_frameworks!和ENABLE_BITCODE = 'NO',否则云打包失败
示例错误:调用 plugin.doSomething({x: 1}) 后 JS 无响应 → 很可能是因为你在后台线程里直接 return 了,没调 callback;或者 callback 参数含 Date、NSData 等非 JSON 类型,被静默丢弃。
调试时别只看 console,真机 + Xcode 日志才是关键
JS 层的 console.log 和 uni.showToast 对原生逻辑无感知。真正有效的调试链路是:
- 在 UTS 中用
console.log只能输出到 HBuilderX 控制台(仅限 dev 模式),上线后失效 - 在传统 OC/Swift 插件中,必须用
NSLog(@"msg: %@", obj),然后在 Xcode → Devices and Simulators → 选中你的真机 → 点 Open Console 查看实时日志 - 若用 Safari 调试 JS 层调用是否发出,打开 Safari → Develop → [你的设备名] → [HBuilder App],检查
uni.invokePlugin是否报错(如plugin not found说明 class 名没对上,或 manifest.json 里没声明ios.class)
常见断点失效原因:Xcode 没正确关联源码(尤其是 UTS 编译出的 Swift 文件路径嵌套深),或插件没被 Link 进主工程(检查 HBuilder-uniPluginDemo 的 Link Binary With Libraries 列表里有没有你的 .framework)。
最常被忽略的一点:UTS 插件的 iOS 方法签名,在云打包时会被自动映射为 Swift 的 func xxx(param: Any?) -> Any?,但如果你在 JS 层传了 undefined 或 null,Swift 侧收到的是 NSNull,不是 nil——做判空时得用 param === null,而不是 param == nil。


















