原生插件必须离线打包验证，且需严格遵循目录结构、命名规范、配置同步等要求，否则真机预览和云打包均无法加载；nativeplugins目录须位于项目根目录，插件ID、package.json与dcloud_uniplugins.json中的class路径须完全一致，Android调试必须通过UniPlugin-Hello-AS工程进行。
原生插件不是“写完就能用”，必须走离线打包验证，否则真机预览和云打包都加载不到——这是 90% 新手卡住的第一关。
nativeplugins 目录位置和命名必须严格匹配
uni-app 不会扫描任意路径下的原生代码，nativeplugins 是唯一被识别的硬编码目录名，必须手动创建在项目根目录（和 src、manifest.json 同级），大小写敏感、不可嵌套。
- ✅ 正确：
myproject/nativeplugins/my-plugin/package.json - ❌ 错误：
myproject/src/nativeplugins/...、myproject/platforms/android/nativeplugins/...、myproject/NATIVEPLUGINS/... - 错误后果：HBuilderX 编译时完全静默跳过，不报错、不提示、不加载——你改了十次 Java 也没用
- 插件 ID（即目录名）只能含小写字母、数字、短横线，且必须与
package.json中的id字段完全一致
package.json 的 class 路径要和 AAR 内真实类路径一字不差
package.json 里 nativePlugins[0].android.plugins[0].class 声明的类路径，必须和你打包出的 .aar 文件中实际存在的 .class 文件路径完全一致，包括包名层级、大小写、是否带内部类等。
- 常见错误：Java 类写在
com.example.plugin.MyPlugin，但 AAR 打包后实际路径是com/example/plugin/myplugin/MyPlugin.class（IDE 自动生成了子包） - 验证方法：
unzip -l your-plugin.aar | grep "\.class$"，再比对输出路径 - 该类必须继承
UniModule，且可调用方法需加@UniJSMethod注解，否则 JS 端调用时直接报undefined is not a function
Android 调试必须用离线打包工程，不能靠 HBuilderX 真机预览
HBuilderX 的“运行到手机”或“云打包预览”用的是标准基座，它根本不加载你本地 nativeplugins 下的任何插件。想确认逻辑是否跑通，唯一有效方式是集成进 UniPlugin-Hello-AS 这类离线打包工程，在 Android Studio 里真机调试。
- 步骤：把你的插件 module 添加为
app模块的依赖 → 修改app/src/main/assets/dcloud_uniplugins.json注册插件 → 在 Android Studio 中 Run - 关键配置缺一不可：
dcloud_uniplugins.json中的name必须和 JS 里uni.requireNativePlugin('xxx')的字符串一致；class必须和 AAR 中路径一致 - Logcat 中若出现
ClassNotFoundException，大概率是 class 路径或依赖缺失，而不是 JS 调用错了
build.gradle 和依赖版本极易引发 Dex 合并失败
uni-app 插件不是普通 Android Library，它依赖 uniapp-v8-release.aar 提供的运行时桥接能力，因此 Gradle 配置顺序、JDK 版本、support 库版本都必须对齐，否则编译通过但运行时报 NoClassDefFoundError 或直接闪退。
- JDK 推荐用 11（Zulu），JDK 17 在 AS 2023.3+ 上会导致
uniapp-v8-release.aarDex 合并失败 - module 的
build.gradle中，compileOnly fileTree(include: ['uniapp-v8-release.aar'], dir: '../app/libs')必须放在 dependencies 最前面 - support 库版本必须和
uniapp-v8-release.aar内置版本一致，例如androidx.appcompat:appcompat:1.6.1，不能随意升级 - 禁止引入冲突库（如
glide、okhttp），除非你明确处理了版本隔离
最常被忽略的点：package.json 和 dcloud_uniplugins.json 两处 class 路径必须同步更新，AAR 重打包后，很多人只改了前者，忘了后者也要跟着变；还有就是混淆规则没加，导致 release 包里 UniModule 子类被删掉——这些都不会在编译时报错，只会在运行时静默失效。
