liufumingren 34263169ed feat(apk): 增加测试模式(dev:adb 注入开发环境接口地址)
- scripts/dev-adb.cjs:编译期注入 VUE_APP_API_BASE_OVERRIDE(默认取 .env.development.local),打包到 release/android/dev 并可选装机启动
- pack.ps1 新增 -Dev:产物 _dev 后缀 + 单独目录,不覆盖发行包、不触发发布上传
- package.json 新增 dev:adb / build:app-plus:dev
- README 补充两种模式的接口地址来源、正反向校验与真机日志查看方式
2026-10-02 21:57:15 +08:00

102 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 <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」的提示。
## 5+ 模块(aar)与 manifest 里勾选的模块
离线打包**不会**自动带上 `src/manifest.json` 里勾选的模块,必须同时满足两个条件:
1. 该模块的 aar 放进 `HBuilder-Integrate-AS/simpleDemo/libs/`;
2. 在 `simpleDemo/src/main/assets/data/dcloud_properties.xml` 里声明对应 `<feature>`。
否则运行时才报错(例如蓝牙会提示「缺少蓝牙模块」,且代码里找不到该文案——它来自 5+ 运行时)。
当前已包含:
| 模块 | 提供物 | 备注 |
|---|---|---|
| Bluetooth(蓝牙打印 / 蓝牙扫码枪) | `libs/Bluetooth-release.aar` + `<feature name="Bluetooth" value="io.dcloud.feature.bluetooth.BluetoothFeature"/>` | 从离线 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` 增加同名 `<feature>` 行——**类名最快来源是从已发布的云端 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` 时才会执行;本仓库不提供该文件,因此默认不会上传。