删除 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。
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)
- 生成 App 资源:
npm run build:app(或 HBuilderX「发行 → 原生App-本地打包」,产物路径写到pack-config.json的wwwSource) - 一条命令编译前端 + 注入配置并打包 APK:
即npm run build:apknode 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
- 探测 JDK / Android SDK 并生成
- 常用参数:
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
- 方案 A:升级项目编译器到 5.24 对应版本(
- 官方文档:https://nativesupport.dcloud.net.cn/AppDocs/README
其他
- 若只用「云打包」(HBuilderX 发行 → 原生App-云打包),无需本目录,也不需要 Android Studio