uni-app如何调用原生插件 uni-app原生插件开发与配置流程-uni-app-PHP中文网

uni-app调用原生插件必须确保三处严格对齐：前端uni.requireNativePlugin()参数名、nativeplugins/目录下插件文件夹名、以及package.json中name字段和Android/iOS平台class值，任一拼写或路径错误均导致undefined或调用失败。

uni-app如何调用原生插件 uni-app原生插件开发与配置流程

uni-app 调用原生插件不是「写完就能用」，关键在于三处必须对齐：前端 uni.requireNativePlugin 的名字、nativeplugins/ 目录结构、以及 Android/iOS 工程中声明的插件类名或模块名。任一环节拼写或路径错一位，undefined 或 requireNativePlugin is not a function 就立刻出现。

nativeplugins 目录必须手动创建且命名严格固定

uni-app 不会自动识别原生插件，必须在项目根目录下显式创建名为 nativeplugins 的文件夹（注意大小写、无空格、无横线）。这个名称是硬编码进 uni-app 构建逻辑的，改任何字符都会导致插件完全不加载。

nativeplugins/YourPluginName/ 是插件一级目录，名字要和前端 uni.requireNativePlugin('YourPluginName') 中传入的字符串完全一致（区分大小写）
Android 插件必须在 nativeplugins/YourPluginName/android/ 下放 .aar 或 .jar 文件；iOS 插件则必须在 nativeplugins/YourPluginName/ios/ 下放 .framework 或源码文件
不能把 .aar 放进 android/libs/ 这类子目录里——uni-app 只认 android/ 直接子目录下的二进制文件

package.json 必须放在 nativeplugins/插件名/ 根下且字段不可省略

每个插件目录下必须有 package.json，它不是可选配置，而是 uni-app 插件注册的唯一依据。缺失或格式错误会导致插件被静默忽略。

"name" 字段值必须与插件目录名、uni.requireNativePlugin() 参数三者完全一致
Android 插件必须包含 "_dp_nativeplugin.android.plugins" 数组，其中 "class" 值要精确到完整 Java 类路径，比如 "com.example.myplugin.MyModule" ——少一个点或大小写错，运行时报 NoClassDefFoundError
iOS 插件的 "_dp_nativeplugin.ios" 配置中，"class" 对应的是 Objective-C 类名（如 DCTestUniPlugin），不是 Swift 类名，也不是模块名
如果插件只支持某平台，另一平台字段可省略，但不能留空对象或写 null

uni.requireNativePlugin 返回 undefined 的常见原因

这不是 JS 报错，而是插件根本没注册成功。别急着查代码逻辑，先确认这几点：

uni-app

uni-app 是基于 Vue 的跨端开发框架，适合开发 H5、App、小程序、鸿蒙和多端业务应用。

下载

HBuilderX 项目是否已启用「原生插件支持」？检查 manifest.json → app-plus → usingComponents 是否为 true；未开启时所有原生插件均不可用
是否在真机或自定义基座中运行？Web 和模拟器不支持原生插件，HBuilderX 默认运行的是标准基座，需用「发行 → 原生App-云打包」或「制作自定义调试基座」才能生效
Android 插件的 minSdkVersion 是否高于当前测试设备系统版本？例如插件设了 23，而手机是 Android 6.0（API 23），实际会因版本不匹配被跳过
iOS 插件是否已正确 link 到 HBuilder-uniPluginDemo 工程？Xcode 中看不到插件 target 或报 ld: framework not found，说明 SDK 路径引用失效

Android 插件 class 名和 iOS 类名容易混淆

同一个插件在两端的注册入口完全不同，但开发者常误以为可以复用名字。Java 的 class 是运行时加载的全限定类名；Objective-C 的 class 是编译期符号名，两者无映射关系。

Android 端：看 build.gradle 里的 namespace + Java 类文件路径，例如 namespace 'io.dcloud.uniplugin.richalert' + RichAlertWXModule.java → "class": "io.dcloud.uniplugin.richalert.RichAlertWXModule"
iOS 端：打开 Xcode，在插件 target 的 Classes/ 下找 .m 文件，其 @implementation XXX 后面的名字就是 class 值，比如 @implementation DCRichAlert → "class": "DCRichAlert"
千万别把 iOS 的 DCRichAlert 当成 Android 的类名去填，也别把 Android 的 RichAlertWXModule 拿去 iOS 的 package.json 里用