liufumingren a34b194211 chore(release): 版本号 1.0.34 + 精简 APK 打包入口
删除 android:pack(= build:apk 同一脚本的别名) 与 android:prepare(pack.ps1 内部直接调 prepare.cjs 文件,无需别名);发布入口统一 build:apk,真机调试 dev:adb,android:pack:raw 保留为两者共用的内部步骤。同步 scripts/build-apk.cjs 用法注释与 config/README.md、android-offline/README.md。
2026-09-25 03:04:51 +08:00

81 lines
4.8 KiB
Markdown

# Android 离线打包脚手架
本目录用于存放 DCloud 官方 **Android 离线打包 SDK**,用于用 Android Studio 本地打包 APK。
## 1. 下载 SDK
**最新正式版:HBuilderX 5.24.2026081301(2026-08-13 发布)**
- 百度云:https://pan.baidu.com/s/1AFjLggD7g6ue0iKgZ8yVyA (提取码: jrrb)
- 和彩云:https://yun.139.com/shareweb/#/w/i/2w2KLgoTHEPz0
下载后把 zip 解压到本目录,预期结构:
```
android-offline/
├── SDK/ # libs、assets 等原生库
├── HBuilder-Integrate-AS/ # Android Studio 集成工程(导入这个)
├── UniPlugin-Hello-AS/ # 原生插件开发参考工程(可选)
└── AndroidManifest.xml 等说明文件
```
## 2. 配置(先做,无需等 SDK)
**配置已统一到项目根 `config/` 目录**:`config/android.json` 为本地配置(含密钥,git 不跟踪),模板为 `config/android.example.json`。字段说明与统一约定见 **`config/README.md`**。
首次使用:复制 `config/android.example.json` 为 `config/android.json` 后填写(签名密钥放入本目录 `keystore/`)。
| 字段 | 说明 |
|---|---|
| `appId` | uni-app appid,已预填 `__UNI__900BDC1`(与散单项目共用,复用其离线打包 Key) |
| `appKey` | DCloud AppKey,与散单项目共用(散单在 dev.dcloud.net.cn 为 `__UNI__900BDC1` 申请),复用即可 |
| `appName` | 应用名(安装后桌面显示名称) |
| `packageName` | Android 包名(唯一标识,发布后不可改) |
| `abis` | CPU 架构列表,默认 `["x86", "armeabi-v7a", "arm64-v8a"]` 三种全覆盖 |
| `icon` | 图标路径(相对项目根),已生成 `android-offline/icon/app-icon.png`(1024x1024,可替换自己的图) |
| `splash` | 启动图路径(相对项目根),已生成 `android-offline/splash/splash.png`(1920x1080 横屏,可替换自己的图) |
| `signing.keystore` | 签名文件路径(相对项目根),把 keystore 放进 `android-offline/keystore/`(整个目录 git 不跟踪) |
| `signing.storePassword` / `keyAlias` / `keyPassword` | 签名密码信息 |
> 生成 keystore:`keytool -genkey -v -keystore keystore/release.keystore -alias wms -keyalg RSA -keysize 2048 -validity 36500`
>
> **版本统一**:版本号由项目根 `package.json` 的 `version` 三段式(X.Y.Z)统一管理,exe 与 APK 都使用它。APK 的 `versionCode` 自动推导:`X*1000000 + Y*1000 + Z`,每段 0-999(如 1.0.1 → 1000001、1.0.101 → 1000101、1.1.1 → 1001001,严格递增)。发布新版只需改 `package.json` 的 `version`。
> 最大版本 999.999.999 → versionCode 999999999(约 10 亿),远低于 Android/应用商店的 21 亿上限,无需担心溢出。
>
> 图标/启动图为脚本生成(深蓝渐变 + 包裹箱 + 扫描线,无文字)。需要调整设计时改 `scripts/gen-android-assets.ps1` 后运行:
> `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\gen-android-assets.ps1`
## 3. 离线打包流程(命令打包,无需 Android Studio)
1. 生成 App 资源:`npm run build:app`(或 HBuilderX「发行 → 原生App-本地打包」,产物路径写到 `pack-config.json` 的 `wwwSource`)
2. 一条命令编译前端 + 注入配置并打包 APK:
```
npm run build:apk
```
即 `node scripts/build-apk.cjs` —— **强制生产编译**(注入生产接口域名、并校验产物里不得有开发地址,否则中止),再调用 `pack.ps1`,自动完成:
- 探测 JDK / Android SDK 并生成 `local.properties`
- 执行准备(`prepare.cjs`):拷贝 App 资源到工程、覆盖图标/启动图
- `gradlew assembleRelease` 命令行构建(Gradle 动态读取 `config/android.json` 与 `package.json` 获得包名/版本/签名/应用名/appid/appKey)
- APK 输出到 `release/android/wms-worker-station_v{版本}_release.apk`
3. 常用参数:
```
pack.ps1 -Clean # 全量重编
pack.ps1 -Timestamp # 产物名带时间戳
pack.ps1 -VersionName 1.0.2 # 覆盖版本(写回 package.json,versionCode 自动推导)
pack.ps1 -NoInject # 跳过注入(已注入过时用)
```
> 若想用 Android Studio 图形界面构建,打开 `HBuilder-Integrate-AS` 工程即可(命令打包与 IDE 打包共用同一工程)。
> 工程已纳入 git 提交(保证发布基座一致),工程内不含任何密码;local.properties、build/ 等本地产物已忽略。
## ⚠️ 版本匹配提醒
- 离线 SDK 版本需与**生成 App 资源的 HBuilderX 版本一致**。当前项目 CLI 编译器版本为 5.07,而最新 SDK 对应 HBuilderX 5.24:
- 方案 A:升级项目编译器到 5.24 对应版本(`npx @dcloudio/uvm@latest` 后重新 `npm install`),或直接用 HBuilderX 5.24 打开项目生成本地打包资源
- 方案 B:到官方"历史版本"页下载与 5.07 匹配的旧 SDK
- 官方文档:https://nativesupport.dcloud.net.cn/AppDocs/README
## 其他
- 若只用「云打包」(HBuilderX 发行 → 原生App-云打包),无需本目录,也不需要 Android Studio