uni-app原生插件必须严格置于根目录nativeplugins下，大小写敏感且不可嵌套；package.json中class路径须与aar内真实类路径完全一致；android调试须通过离线打包工程验证，前端需用uni.requirenativeplugin按id加载。
uni-app 原生插件必须放在 nativeplugins 目录下才能被识别
uni-app 不会自动扫描任意目录下的原生代码，nativeplugins 是硬性约定路径，必须手动在项目根目录创建，大小写不能错，也不能嵌套在其他文件夹里。如果放错位置（比如放在 src/nativeplugins 或 platforms/android/nativeplugins），HBuilderX 编译时完全不会加载，也不会报错——这是最常被忽略的“静默失败”点。
该目录结构必须严格遵循官方格式：
-
nativeplugins/YourPluginName/package.json（必需） -
nativeplugins/YourPluginName/android/your-plugin.aar（Android 端必需） -
nativeplugins/YourPluginName/ios/YourPlugin.framework（iOS 端可选，但双端插件需同时提供）
package.json 里 _dp_nativeplugin.android.plugins 的 class 必须与 AAR 中实际类路径完全一致
很多开发者打包完 AAR 后，只改了 package.json 里的 class 字段，却没注意 AAR 内部的 class 文件路径是否匹配。例如你声明了 "class": "com.example.myplugin.MyPlugin"，但 AAR 中实际编译出的 class 是 com.example.myplugin.myplugin.MyPlugin（多了一级包名），运行时就会抛出 ClassNotFoundException，且错误日志不显眼，只出现在 Android Logcat 的 warn 级别中。
验证方法很简单：用 unzip -l your-plugin.aar | grep "\.class$" 查看真实类路径，再比对 package.json；同时确保该类继承 UniModule，并用 @UniJSMethod 注解标记可调用方法。
Android 插件调试必须走离线打包工程，不能直接在 HBuilderX 里真机预览
uni-app 的真机调试（包括“运行到手机”和“云打包预览”）默认使用标准基座，它不加载你本地开发的原生插件。想验证逻辑是否正确，唯一可靠方式是：把插件集成进 uniplugin-hello-as 这类离线打包工程，在 Android Studio 中运行调试。
关键配置缺一不可：
-
android/app/src/main/assets/dcloud_uniplugins.json中添加你的插件name（必须和package.json中的id一致） -
android/app/src/main/AndroidManifest.xml中<meta-data android:name="dcloud_appkey" android:value="..."></meta-data>的值，要与你在 DCloud 后台为该包名申请的 AppKey 完全一致 - 签名配置（
signingConfigs）必须和申请 AppKey 时用的 keystore 完全相同，否则离线包无法启动
调用前必须先 uni.requireNativePlugin，且名字要和 package.json.id 对齐
前端 JS 侧不能直接 new YourPlugin() 或 import，必须显式加载：
const myPlugin = uni.requireNativePlugin('my-plugin-id') // 注意：不是 package.json.name，而是 id
这个 id 字段必须和 package.json 中的 id 完全一致（包括大小写、连字符），否则返回 undefined。常见错误是误填成目录名或 name 字段值。另外，该调用必须在 onLaunch 或页面 onLoad 之后执行，不能放在模块顶层——因为 uni-app 生命周期未就绪时，桥接环境尚未初始化。
最后提醒一句：iOS 插件调试更麻烦，没有类似 uniplugin-hello-as 的成熟调试工程，基本靠反复云打包验证，所以 Android 端务必先调通再动 iOS。
