# 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` | ✅ | ## 一键打包 ```powershell 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 里重新取素材的办法: ```powershell # 解包 APK 后用 aapt2 查出图标文件名,再按尺寸挑最大的一张 & "$env:ANDROID_HOME\build-tools\35.0.0\aapt2.exe" dump badging | 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`,所以 `` 上显式声明了 `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` 时才会执行;本仓库不提供该文件,因此默认不会上传。