- 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 补充两种模式的接口地址来源、正反向校验与真机日志查看方式
102 lines
7.4 KiB
Markdown
102 lines
7.4 KiB
Markdown
# 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` 时才会执行;本仓库不提供该文件,因此默认不会上传。
|