原生插件配置必须放在app-plus节点下，根节点或h5、mp-weixin等节点下写nativePlugins无效；字段名大小写敏感，须严格为"nativePlugins"；name必须与package.json中name完全一致；插件须置于nativeplugins/插件ID/目录且含有效package.json；修改后需重启HBuilderX并重新制作自定义基座或云打包。
manifest.json里原生插件配置必须放在app-plus节点下
直接在根节点或h5、mp-weixin节点下写nativePlugins，打包时完全无效。HBuilderX只认app-plus下的配置，且字段名大小写敏感——写成nativeplugins或NativePlugins都会被忽略。
正确结构示例：
{
"name": "MyApp",
"appid": "",
"description": "",
"versionName": "1.0.0",
"versionCode": 1,
"transformPx": false,
"app-plus": {
"usingComponents": true,
"nvueStyleCompiler": "uni-app",
"splashscreen": {
"alwaysShowBeforeRender": true,
"waiting": true,
"autoclose": true,
"delay": 0
},
"nativePlugins": [
{
"name": "barcode-scanner",
"id": "com.example.barcode",
"class": "com.example.barcode.BarcodeModule",
"type": "module"
}
]
}
}
-
name必须与插件包内package.json中的name字段**完全一致**（区分大小写、不能有空格或中文） -
id建议与package.json中的id对齐，云端打包时用于唯一识别插件 -
class必须是完整类路径，Android为package.ClassName，iOS需对应OC/Swift的导出类名 - 多个插件用数组，不要合并成一个对象
插件目录结构和自动识别失败的常见原因
HBuilderX不会扫描任意路径下的插件，它只从项目根目录的nativeplugins/子目录中加载。如果插件放错位置，即使manifest.json写对了，也会报“当前运行的基座不包含原生插件[xxx]”。
- 插件必须解压到
nativeplugins/插件ID/，例如nativeplugins/com.example.barcode/ - 该目录下必须包含有效的
package.json（含name、id、platforms等字段） - 插件包不能是压缩包（.zip/.rar），必须是已解压的文件夹结构
- 修改
nativeplugins后，必须重启HBuilderX或执行“菜单 → 运行 → 清除缓存并重新运行”
自定义AndroidManifest.xml与manifest.json的冲突处理
HBuilderX 3.6+支持在项目中直接放AndroidManifest.xml，但它的内容会和manifest.json中app-plus下的权限、meta-data等配置合并。一旦重复声明，打包会失败或行为不可控。
- 避免在
AndroidManifest.xml中再次声明android.permission.INTERNET等已在manifest.json中通过permissions配置过的权限 - 如需添加
meta-data，优先写在manifest.json的app-plus → metadata字段；若必须用XML，确保android:name不与manifest.json生成的冲突 -
package属性值必须与云端打包时填写的Android包名一致，否则签名和推送会失效 - 真机运行不生效？大概率是没走云打包——
AndroidManifest.xml仅在云打包时参与构建，本地调试基座不读取它
启动图、图标等静态资源必须用static/相对路径
很多人把splashscreen或icons配成绝对路径或网络地址，结果App启动页永远是白屏或默认图标。uni-app在编译时只打包static/目录下的文件，且路径必须以static/开头。
- 正确写法：
"splashscreen": { "images": { "android": "static/splash/android.png" } } - iOS启动图必须用
Storyboard格式（.storyboard文件），不能用PNG拼接；鸿蒙则复用android字段路径 - 图标尺寸必须严格符合平台规范：Android要求mipmap-xxxhdpi等多密度文件夹，iOS要求1024×1024等特定尺寸
- 改完
manifest.json后不生效？90%是因为没重新制作自定义基座或没走云打包
