uni-app 引入第三方原生插件必须严格对齐三处：nativeplugins 目录结构（根目录手动创建，全小写无特殊字符）、package.json 元数据（name 与调用名一致，platforms 字段完整准确）、前端 uni.requireNativePlugin() 调用名（大小写敏感、逐字符匹配），缺一不可，否则报 undefined 或 not a function。
直接说结论：uni-app 引入第三方原生插件，不是「放进去就能用」，而是必须同时满足三处严格对齐——nativeplugins 目录结构、package.json 元数据、前端 uni.requireNativePlugin() 调用名，缺一不可，错一位就报 undefined 或 requireNativePlugin is not a function。
nativeplugins 目录必须手动创建且命名零容错
uni-app 不会自动扫描或识别插件，nativeplugins 是硬编码路径，必须在项目根目录下**手动创建**，名称必须是全小写、无空格、无横线、无中文的 nativeplugins（不是 native-plugins，也不是 NativePlugins）。
-
nativeplugins/YourPluginName/是插件一级目录，名字要和前端uni.requireNativePlugin('YourPluginName')中传入的字符串**完全一致（大小写敏感）** - Android 插件文件（
.aar或.jar）必须直接放在nativeplugins/YourPluginName/android/下，不能嵌套进libs/或dist/子目录 - iOS 插件同理，
.framework或源码必须放在nativeplugins/YourPluginName/ios/下，且不能有额外层级
package.json 是插件注册的唯一依据
每个插件目录下（即 nativeplugins/YourPluginName/）必须存在 package.json，它不是可选配置，缺失或格式错误会导致插件被静默忽略。
-
name字段必须与目录名、前端调用名完全一致 -
platforms.android.class必须填 Android 端实现类的完整包名+类名（如com.example.uniplugin.MyModule），不能漏掉com.开头 -
platforms.ios.module对应 iOS 的模块名（Swift 类名或 OC 类名），大小写、拼写必须与实际代码一致 - 字段不能缩写或省略，例如
platforms不能写成platform，class不能写成className
前端调用名必须和三处完全一致
前端 JS 层调用时，uni.requireNativePlugin() 的参数是整个链路的“钥匙”，它必须和以下三者逐字符匹配：
-
nativeplugins/下的子目录名 -
package.json中的name字段 -
package.json中platforms.android.class的类名（仅 Android）或platforms.ios.module（仅 iOS）的声明名
常见错误现象：TypeError: uni.requireNativePlugin is not a function → 多半是 HBuilderX 没启用原生插件支持，或未使用自定义基座；Cannot read property 'xxx' of undefined → 基本就是这三处有一处拼写/大小写/路径不一致。
云打包前必须用自定义基座调试
uni-app 的原生插件**无法在普通运行（如 H5 或模拟器热更新）中生效**，必须通过「自定义基座」方式真机调试或云打包。
- 自定义基座需用你当前 HBuilderX 版本对应离线 SDK 构建，版本不匹配会导致插件加载失败
- Android 自定义基座需签名证书与
dcloud_control.xml中配置一致，否则插件注册失败 - 云打包时，
nativeplugins目录不会被自动包含，必须确认 HBuilderX 项目设置里已勾选「使用原生插件」并正确识别了插件目录 - 调试阶段建议先在
onLaunch中打印uni.requireNativePlugin('YourPluginName')结果，非undefined才说明加载成功
最容易被忽略的是：插件类继承的必须是 UniModule（不是 BaseModule 或自定义父类），且暴露方法必须加 @UniJSMethod 注解，否则即使加载成功也无法调用具体方法。
