uni-app插件化开发必须严格遵循物理路径（根目录nativeplugins）、元数据声明（class路径与AAR一致）和原生工程集成（离线打包验证）三步闭环，缺一不可；放错目录、路径不匹配或跳过离线打包验证是插件失效的主因。
uni-app 的插件化开发不是靠 npm install 或 import 就能生效的，必须走官方约定的物理路径 + 元数据声明 + 原生工程集成三步闭环。放错目录、class 路径不匹配、跳过离线打包验证，这三类问题占了 90% 以上的“插件不工作”案例。
nativeplugins 目录必须严格位于项目根目录
uni-app 不会扫描 src/、platforms/ 或任意子目录下的原生代码。nativeplugins 是硬编码识别路径，大小写敏感，不可嵌套。常见错误包括：
- 把插件放在
src/nativeplugins/MyPlugin—— 编译时静默忽略，无任何提示 - 写成
NativePlugins或native-plugins—— HBuilderX 完全不识别 - 用云打包或真机预览调试 —— 标准基座不加载本地
nativeplugins，必须走离线打包工程
package.json 中的 class 路径必须与 AAR 内真实类完全一致
声明的 "class": "com.example.myplugin.MyPlugin" 必须和 AAR 解压后实际存在的 class 文件路径一模一样。否则运行时抛 ClassNotFoundException，且只在 Android Logcat 的 warn 级别出现，极难定位。
- 用
unzip -l your-plugin.aar | grep "\.class$"查看真实路径 - 确认该类继承
UniModule，且方法用@UniJSMethod注解标记 - Android Studio 打包时若开启混淆，需在
proguard-rules.pro中保留UniModule及其子类
Android 插件必须通过离线打包工程验证，不能依赖 HBuilderX 真机预览
前端调用 uni.requireNativePlugin('my-plugin-id') 成功，不代表插件逻辑真的跑起来了。标准基座（包括“运行到手机”）根本不加载 nativeplugins 下的任何内容。
- 必须将插件 AAR 集成进
UniPlugin-Hello-AS这类离线打包工程 - 在
android/app/src/main/assets/dcloud_uniplugins.json中添加插件name（必须和package.json中的id一致） - 在
AndroidManifest.xml中确保meta-data的dcloud_appkey值有效（与 DCloud 后台注册一致）
最容易被忽略的是：iOS 端若要支持，nativeplugins/YourPluginName/ios/YourPlugin.framework 必须是静态库（Mach-O Type = Static Library），且 Xcode 主工程需在 Link Binary With Libraries 和 Dependencies 中同时引用该 framework —— 少一步，运行时就报 undefined symbol。
