liufumingren 06d58a5a71 chore(apk): 移植 Android 离线打包流水线(命令行出 APK,无需 HBuilderX)
- android-offline/:DCloud 离线集成工程(simpleDemo/libs 含 5+ Runtime aar)+ pack.ps1 + prepare.cjs
- 包名 com.gztbyc.pda_wms、appId __UNI__0B3DAD3、BootReceiver 迁到新包名目录
- AndroidManifest 补齐权限(与 src/manifest.json 对齐)、新增蓝牙权限与 usesCleartextTraffic(生产接口为 http)
- prepare.cjs 默认资源目录改为 dist/build/app-plus,注入到 assets/apps/__UNI__0B3DAD3/www 并对齐 compilerVersion
- config/:android.example.json 模板 + README(appKey 与 appId/包名/证书指纹绑定说明);android.json 与 keystore 均不提交
- scripts/build-apk.cjs + npm run build:apk / android:pack:raw:生产编译(含地址校验)→ gradle 出包到 release/android
- .gitignore 忽略 keystore、config/android.json、SDK、生成的 www 与 release
2026-10-02 21:12:15 +08:00
..

config 目录说明

本目录存放打包/发布相关配置。含密码等敏感信息的一律不提交 git,配套的 *.example.json 模板提交。

文件 说明 是否提交
android.json Android 离线打包本地配置(appKey、签名密码等) ❌
android.example.json 上述配置的模板,首次使用复制为 android.json ✅

android.json 字段

字段 说明
appId uni-app appid。本项目为 __UNI__0B3DAD3,不要与工作台/散单的 __UNI__900BDC1 混用
appKey DCloud 离线打包 Key,按 appId + packageName + 签名证书 SHA-256 三者绑定
appName 桌面显示的应用名(构建时写入 resValue app_name)
packageName Android 包名(applicationId 与 gradle namespace 都由它决定,发布后不可更改)
abis CPU 架构。此处与 src/manifest.json 的 abiFilters 保持一致(armeabi-v7a、arm64-v8a)
icon / splash 图标/启动图路径(相对项目根),prepare.cjs 会用它们覆盖 res/ 下的同名资源
wwwSource App 资源目录。留空则依次尝试 unpackage/resources/<appId>/www、dist/build/app-plus
runtimeVersion 离线 SDK 的 5+ Runtime 版本。prepare.cjs 会把 www 内 manifest.json/app-config-service.js 的 compilerVersion 对齐到该值,避免启动时弹「HBuilderX %s 编译 / 手机端 SDK %s」提示
signing.keystore 签名文件路径(相对项目根),放在 android-offline/keystore/(该目录 git 不跟踪)
signing.storePassword / keyAlias / keyPassword 签名密码与别名,自己填写,不要提交

appKey 务必与三者一致

appKey 失效的典型表现:APK 能装能开,但启动即白屏并提示「未配置appkey或配置错误」。此时按顺序核对:

  1. appId 是否为 __UNI__0B3DAD3;
  2. packageName 是否与申请 Key 时填写的包名一致;
  3. 证书 SHA-256 是否与申请 Key 时使用的一致:
    keytool -list -v -keystore android-offline\keystore\<你的证书> -alias <别名>
    
    输出里的 SHA256: 即为指纹。

需要更换包名或证书时,要先去 https://dev.dcloud.net.cn → 应用详情 → Android → 离线打包 Key 管理 重新申请(需填包名与证书 SHA-256)。

首次使用

  1. 确认 config/android.json 已存在(本仓库已预填非敏感项),填写 appKey、keyAlias、storePassword、keyPassword;
  2. 确认 android-offline/keystore/ 下有对应 keystore;
  3. 执行 npm run build:apk(= 生产编译 + 产物地址校验 + 离线打包)。