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
..
2026-09-20 22:57:22 +08:00

Android 离线打包脚手架

本目录用于存放 DCloud 官方 Android 离线打包 SDK,用于用 Android Studio 本地打包 APK。

1. 下载 SDK

最新正式版:HBuilderX 5.24.2026081301(2026-08-13 发布)

下载后把 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