# 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 打包 npm run dev:adb # 测试包:注入开发地址 → 打包 → 装机 → 启动(产物进 release/android/dev) npm run dev:adb -- --prod-api # 测试包但指向生产(排查线上问题时用) npm run dev:adb -- --api=http://192.168.1.10:6060 --no-install ``` 产物:`release/android/wms-pda_v{版本}_release.apk`(测试包为 `release/android/dev/wms-pda_v{版本}_release_dev.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」的提示。 ## 5+ 模块(aar)与 manifest 里勾选的模块 离线打包**不会**自动带上 `src/manifest.json` 里勾选的模块,必须同时满足两个条件: 1. 该模块的 aar 放进 `HBuilder-Integrate-AS/simpleDemo/libs/`; 2. 在 `simpleDemo/src/main/assets/data/dcloud_properties.xml` 里声明对应 ``。 否则运行时才报错(例如蓝牙会提示「缺少蓝牙模块」,且代码里找不到该文案——它来自 5+ 运行时)。 当前已包含: | 模块 | 提供物 | 备注 | |---|---|---| | Bluetooth(蓝牙打印 / 蓝牙扫码枪) | `libs/Bluetooth-release.aar` + `` | 从离线 SDK 的 `SDK/libs/` 复制;本工程最初缺这一项(骨架克隆自不使用蓝牙的项目) | | Barcode / Camera / File / Storage / Console 等 | `libs/lib.5plus.base-release.aar` | 基础运行时自带 | | Webview-x5 | 未单独引入 | 已比对线上云打包 APK:其原生库与本工程完全一致(无 X5 专属 so),故保持一致 | 新增其他模块时:到离线 SDK 的 `SDK/libs/` 找同名 aar(命名通常是 `<模块>-release.aar`,如 `geolocation-amap-release.aar`、`share-weixin-release.aar`、`speech-release.aar`),复制到 `libs/`,并在 `dcloud_properties.xml` 增加同名 `` 行——**类名最快来源是从已发布的云端 APK 里抄**: ```powershell # 解包云端 APK 后对比两份配置,差异即为缺失的模块声明 # (线上包 assets/data/dcloud_properties.xml vs 本工程同名文件) ``` 验证模块是否真的打进包里: ```powershell tar -xf release\android\wms-pda_v*.apk -C $env:TEMP\apkchk findstr /m /c:"io/dcloud/feature/bluetooth" $env:TEMP\apkchk\*.dex ``` ## 首次使用清单 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` 时才会执行;本仓库不提供该文件,因此默认不会上传。