HBuilderX与离线SDK版本必须严格匹配，否则导致build.gradle报错、AndroidManifest被覆盖或资源丢失；需通过“帮助→关于”查HBuilderX版本（如3.8.12.20231215），再下载名称含相同数字的SDK包，仅保留HBuilder-Integrate-AS/simpleDemo目录，将uni-app输出的unpackage/res/android复制至对应apps子目录，并确保applicationId、keystore、dcloud-key等配置完全一致。
直接用 hbuilderx 本地打包是最可行的路径，云打包受限多、无法改原生代码、隐私合规整改时束手无策。
确认 HBuilderX + 离线 SDK 版本严格匹配
离线打包失败 80% 出在版本错配。HBuilderX 的内置编译器和离线 SDK 必须完全一致，否则 build.gradle 报错、AndroidManifest.xml 被覆盖、甚至资源找不到。
- 查当前 HBuilderX 版本：菜单栏「帮助 → 关于」，例如显示
3.8.12.20231215 - 去 DCloud 官网下载对应离线 SDK，名称必须含相同数字，如
3.8.12.81924（不是“最新版”，而是“匹配版”） - 解压后只保留
HBuilder-Integrate-AS/simpleDemo/目录，其余可删 - 把你的 uni-app 项目输出的
unpackage/res/android整个目录，复制进simpleDemo/src/main/assets/apps/下对应子目录（如__UNI__XXXXXXX/）
签名证书必须用 .jks 或 .keystore，且参数全程一致
用 keytool 生成时别图省事跳过关键参数，否则打包能过、安装失败、上架被拒。
- 执行命令必须带
-keyalg RSA -keysize 2048 -validity 10000，有效期少于 3650 天的应用市场会拒绝 -
-alias值要记牢，后续manifest.json和 Android Studio 都要用同一个别名 - 证书文件建议放项目外独立目录（如
~/keys/myapp-release.jks），避免误提交到 Git - 在
manifest.json的app-plus → distribute → android节点里填全四字段：keystore、storepassword、keypassword、keyalias
Android Studio 编译前必须手动改三个地方
离线 SDK 模板是通用工程，不改就编译，APK 装不上、闪退、权限缺失都是默认配置惹的祸。
- 打开
simpleDemo/app/build.gradle，修改applicationId为你的包名（如com.example.myapp），必须和manifest.json里的appid及 DCloud 后台填的包名**完全一致** - 打开
simpleDemo/app/src/main/AndroidManifest.xml，检查android:usesCleartextTraffic="true"（调试期需要，发布前删掉） - 打开
simpleDemo/app/src/main/assets/data/dcloud_control.xml，确认
打包命令和输出路径别依赖 HBuilderX 图形界面
右键「发行 → 原生 App-本地打包」经常卡住或静默失败，尤其在 Windows 中文路径下。推荐终端直跑 Gradle。
- 进入
simpleDemo/目录，执行：./gradlew assembleRelease（macOS/Linux）或gradlew.bat assembleRelease（Windows） - 成功后 APK 在
simpleDemo/app/build/outputs/apk/release/app-release.apk - 首次运行可能卡在
Downloading https://services.gradle.org/...，需提前配置国内镜像（改simpleDemo/gradle/wrapper/gradle-wrapper.properties中的distributionUrl） - 验证签名：执行
keytool -list -v -keystore your.keystore -alias your_alias，比对 SHA256 是否与 DCloud 后台一致
最容易被忽略的是 dcloud_control.xml 里的 dcloud-key 和 DCloud 后台申请时填的 SHA1 是否匹配——错一个字符，APK 就白屏，且没有任何错误提示。
