WMS_PDA/android-offline
liufumingren f9327397d6 chore(apk): 版本对齐到 1.0.122 并补充打包文档
- package.json 与 src/manifest.json 版本同步为 1.0.122 / versionCode 1000122
- prepare.cjs 增加版本一致性校验(两处不一致时告警)
- 文档补充:版本号单一来源与云打包 versionCode 差异、图标/启动图来源、appKey 与证书指纹匹配
2026-10-02 21:20:14 +08:00
..

Android 离线打包(WMS_PDA)

本目录是 DCloud 官方 Android 离线打包集成工程,用于在本地用命令行出 APK(不需要 Android Studio,也不依赖 DCloud 云打包)。

目录

路径 说明 git
HBuilder-Integrate-AS/ Android Studio 集成工程,已提交(保证发布基座一致)。包名/版本/签名/应用名/appid/appKey 全部由 simpleDemo/build.gradle 在构建时从 config/android.json 与根 package.json 动态读取,工程内不含任何密码 ✅
HBuilder-Integrate-AS/simpleDemo/libs/ 5+ Runtime 等 aar(lib.5plus.base-release.aar、uniapp-v8-release.aar、breakpad、install-apk 等) ✅
keystore/ 签名密钥文件 ❌ (忽略)
icon/ splash/ 图标与启动图源文件,prepare.cjs 用它们覆盖 res/ 下同名资源 ✅
SDK/ DCloud 离线 SDK 解压目录(体积大,约 165MB),仅在需要额外原生模块时才下载 ❌ (忽略)
pack.ps1 命令行打包主脚本(JDK/SDK 探测 → 注入 → gradlew assembleRelease) ✅
prepare.cjs 注入 App 资源、覆盖图标/启动图、对齐 compilerVersion ✅

一键打包

npm run build:apk              # = 生产编译 + 产物地址校验 + 离线打包
npm run build:apk -- -Clean    # gradle 全量重编
npm run build:apk -- -NoInject # 跳过资源注入(已注入过时用)
npm run android:pack:raw       # 跳过前端编译,仅用现有 dist/build/app-plus 打包

产物:release/android/wms-pda_v{版本}_release.apk。版本唯一来源是根 package.json 的 version(X.Y.Z),versionCode 自动推导为 X*1000000 + Y*1000 + Z。

⚠ 版本号要两处同步:package.json.version 与 src/manifest.json 的 versionName/versionCode(后者供 HBuilderX 云打包使用)。prepare.cjs 会在打包前校验两者并告警,避免云包/离线包版本号不一致。

历名包在线上的 versionCode 是云打包时手工填的小数字(如 1.0.121 → 125),而离线方案会得到 1000122 这类值。今后统一用 package.json 推导,不要再手工填小数字,否则切回云打包时会变成「降级安装」被系统拦下。

图标与启动图

文件 来源 尺寸
icon/app-icon.png 从线上 APK(v1.0.121)res/9T.png 提取 512×512
splash/splash.png 从线上 APK res/-u.png 提取 1242×2208(竖屏)

prepare.cjs 会把它们覆盖到 simpleDemo/src/main/res/drawable/{icon,splash}.png。有更高清的原始图标(如 1024×1024)时直接覆盖 icon/app-icon.png 即可。

从任意 APK 里重新取素材的办法:

# 解包 APK 后用 aapt2 查出图标文件名,再按尺寸挑最大的一张
& "$env:ANDROID_HOME\build-tools\35.0.0\aapt2.exe" dump badging <apk路径> | Select-String 'application-icon'

环境要求:JDK 17+(脚本会自动探测 JAVA_HOME、Android Studio JBR 等常见位置)、Android SDK(ANDROID_HOME/ANDROID_SDK_ROOT/local.properties 任一即可)。

与云打包的差异(重要)

  • 签名不同:云打包用的是 DCloud 的证书,本地离线打包用 config/android.json 配置的 keystore。若此前对外发布过云打包版本,切换后签名不一致、无法覆盖安装(需先卸载重装);若包名+签名已被第三方 SDK/推送/应用商店绑定,需要重新登记。
  • 权限来自 AndroidManifest:离线打包不会读取 src/manifest.json 的权限声明,权限必须写在 HBuilder-Integrate-AS/simpleDemo/src/main/AndroidManifest.xml。增删权限时请两处同步,否则会出现「云打包能用、离线包缺权限」的差异。
  • 明文 HTTP:生产接口是 http://qimen.wms.gztbyc.com,所以 <application> 上显式声明了 android:usesCleartextTraffic="true"(Android 9+ 默认禁止明文 HTTP)。日后切 HTTPS 可移除。
  • appKey 校验:appKey 与 appId + 包名 + 证书 SHA-256 严格绑定,不匹配时 APK 能装能开但启动白屏提示「未配置appkey或配置错误」。详见 config/README.md。
  • Runtime 版本提示:prepare.cjs 会把 www 内 manifest.json/app-config-service.js 的 compilerVersion 对齐到 config/android.json 的 runtimeVersion,用于消除启动时「本应用使用 HBuilderX %s 编译,而手机端 SDK 版本是 %s」的提示。

首次使用清单

  1. 在 config/android.json 填 appKey、keyAlias、storePassword、keyPassword(该文件不提交 git);
  2. 把对应证书放入 android-offline/keystore/;
  3. npm run build:apk。

⚠️ appKey 必须与签名证书指纹匹配。线上已发布 APK(云打包,签名证书 SHA-256 d9689a9b…25d6ff)内的 appKey 为 f523d8541674ad75105fa604f5a51a54——它只对该 SHA-256 对应的证书有效。若本地离线打包用的是自有 keystore(android-offline/keystore/ 里那把),需先比对指纹,不一致则到 dev.dcloud.net.cn 重新申请,否则 APK 启动会白屏提示「未配置appkey或配置错误」。比对办法见 config/README.md。

发布上传(scp + latest.json)在 pack.ps1 内,但只有存在 config/deploy.json 时才会执行;本仓库不提供该文件,因此默认不会上传。