# 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