APK离线打包

本地打包操作手册

每日打卡 APP · Android 本地离线打包速查手册
适用环境：Android Studio 2024.3.1 (Ladybug) + JDK 17 + Gradle 8.x
文档定位：日常打 APK 时对照执行，每步都给命令/路径，不解释原理

---

0. 文档说明

• 配套文档：APK打包文档.md（完整原理 + 多种打包方案）
• 本手册只讲离线打包这一条路径（白嫖、强烈推荐）
• 读完本手册后，日常打包只需 3 步：编译前端 → 同步资源 → 点 Build

---

1. 一次性环境配置

这些步骤只需做一次，做完之后再也不用管。

1.1 准备 DCloud 账号与 AppID

步骤	操作
1	注册 https://dev.dcloud.net.cn/
2	完成实名认证（未实名无法创建应用）
3	我的应用 → 新建应用 → 类型选 uni-app
4	记录分配到的 AppID（格式 __UNI__abcd1234）

1.2 填 AppID 到前端 manifest

打开 frontend/src/manifest.json，第 3 行：

"appid": "__UNI__abcd1234"   // ← 改成自己的 AppID

⚠️ 改的是 src/ 下的源码 manifest，不是 dist/build/app/ 下的产物。

1.3 准备 Android Studio

• 版本 ≥ 2024.3.1（Ladybug 或更新）
• JDK 17（顶部菜单 Help → Find Action → 输入 "Choose Boot Java Runtime" → 选 JDK 17）

1.4 下载离线 SDK

1. 打开 https://nativesupport.dcloud.net.cn/AppDocs/SDK包下载
2. 找版本号匹配 HBuilderX 的 SDK（推荐 Android-SDK@3.94+）
3. 下载并解压，目录叫 HBuilder-Integrate-AS

1.5 用 Android Studio 打开壳工程

1. Android Studio → File → Open
2. 选 HBuilder-Integrate-AS 目录
3. 等右下角 Gradle sync 完成（首次 30~60 分钟）

1.6 创建 dcloud_control.xml（含 AppKey）

壳工程里没有这个文件，需要手动创建：

1. 左侧项目树顶部下拉框切换到 Project 视图
2. 找到 app/src/main/assets/
3. 在 assets 上右键 → New → Directory → 命名 data
4. 在 data 上右键 → New → File → 命名 dcloud_control.xml
5. 内容（SDK 3.9+ 写法）：

<?xml version="1.0" encoding="UTF-8"?>
<dcloud_control>
    <app appid="__UNI__abcd1234" 
         appver="1.0.0"
         appkey="从DCloud后台复制的AppKey"/>
</dcloud_control>

拿 AppKey 的方法

1. 登录 https://dev.dcloud.net.cn/
2. 我的应用 → 您的应用 → 基础信息
3. 找到 AppKey，点"显示"按钮复制

⚠️ 三个关键点：

• __UNI__abcd1234 替换成自己的 AppID，必须和 src/manifest.json 里的一致
• appkey 复制时别带前后空格/换行
• SDK 3.0~3.8 版本需要在 AndroidManifest.xml 里用 <meta-data> 单独配，详见下方 6.4 节

1.7 创建 www 资源目录

1. 在 app/src/main/assets/ 上右键 → New → Directory
2. 命名 apps（注意是复数）
3. 在 apps 下新建目录 __UNI__abcd1234（替换成自己的 AppID）
4. 在 __UNI__abcd1234 下新建目录 www

最终目录结构：

app/src/main/assets/
├── data/
│   └── dcloud_control.xml
└── apps/
    └── __UNI__abcd1234/
        └── www/        ← 前端产物要放这里

1.8 Gradle 国内镜像（重要！）

打开 gradle/wrapper/gradle-wrapper.properties，把：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.x-all.zip

改成阿里云镜像：

distributionUrl=https\://mirrors.aliyun.com/macports/distfiles/gradle/gradle-8.x-all.zip

然后 File → Sync Project with Gradle Files 重新同步。

---

2. 配置自动化脚本（一次性）

让"编译前端 + 同步到壳工程"一条命令搞定。

2.1 安装依赖

cd frontend
npm install fs-extra --save-dev

2.2 创建同步脚本

新建文件 frontend/scripts/sync-android.js：

const fs = require('fs-extra');
const path = require('path');

// ⚠️ 改成自己的 AppID
const APPID = '__UNI__abcd1234';

const SRC = path.resolve(__dirname, '../dist/build/app');
const DEST = path.resolve(
  __dirname,
  `../../HBuilder-Integrate-AS/app/src/main/assets/apps/${APPID}/www`
);

fs.copySync(SRC, DEST, { overwrite: true });
console.log(`✅ Synced to ${DEST}`);

2.3 注册 npm script

打开 frontend/package.json，在 scripts 里加：

"scripts": {
  "build:app-android": "...",
  "sync-android": "node scripts/sync-android.js"
}

---

3. 日常打包流程（30 秒出 APK）

改完前端代码后，按顺序执行。

Step 1：编译前端

cd frontend
npm run build:app-android

产物在 frontend/dist/build/app/。

Step 2：同步到壳工程

npm run sync-android

把产物复制到 HBuilder-Integrate-AS/app/src/main/assets/apps/__UNI__abcd1234/www/。

Step 3：出 APK（Android Studio 2024.3.1 路径）

1. 顶部菜单 Build → Build Bundle(s) / APK(s) → Build APK(s)
2. 等右下角通知 ✓ APK(s) generated successfully
3. 点通知里的 locate 跳到产物目录
4. APK 路径：

HBuilder-Integrate-AS/app/build/outputs/apk/debug/app-debug.apk

Step 4：装手机

绝对不要用微信传（会自动改成 .apk.1），推荐：

方式	操作
邮件附件	发给自己，附件不会被改
百度网盘	分享下载链接
USB 直连	最稳

手机上点击 APK → 允许"未知来源" → 完成安装。

---

4. 常用命令速查

# === 前端 ===
cd frontend
npm install                       # 首次或依赖变更时
npm run dev:h5                    # H5 调试，http://localhost:5173
npm run build:app-android         # 编译 Android 资源
npm run sync-android              # 同步到壳工程

# === 后端 ===
cd backend
mvn spring-boot:run               # 启动后端（默认 8080）

# === 端口 / 进程 ===
netstat -ano | grep :8080         # 查谁占用了 8080
taskkill /PID <pid> /F            # 杀进程
adb reverse tcp:8080 tcp:8080     # USB 隧道，把手机的 8080 转到电脑

---

5. 关键路径速查

内容	路径
前端源码	frontend/src/
前端 manifest	frontend/src/manifest.json
前端编译产物	frontend/dist/build/app/
后端请求地址	frontend/src/utils/request.ts
壳工程	HBuilder-Integrate-AS/
AppID 配置	HBuilder-Integrate-AS/app/src/main/assets/data/dcloud_control.xml
wgt 资源目录	HBuilder-Integrate-AS/app/src/main/assets/apps/__UNI__xxx/www/
debug APK 产物	HBuilder-Integrate-AS/app/build/outputs/apk/debug/app-debug.apk

---

6. 常见问题排查

Q1：APK 装上后白屏

99% 是 AppID 没配或配错，检查两处必须一致：

• frontend/src/manifest.json 第 3 行 appid
• HBuilder-Integrate-AS/app/src/main/assets/data/dcloud_control.xml 的 appid

Q2：装上 APP 后请求后端失败

按顺序排查：

检查项	处理
request.ts 里的 BASE_URL	真机调试不能用 localhost，改成电脑局域网 IP
手机和电脑不同 WiFi	改连同一 WiFi
后端没起	cd backend && mvn spring-boot:run
想用 USB 隧道	adb reverse tcp:8080 tcp:8080 后才能用 localhost

Q3：Gradle 同步失败

• 检查 Android Studio 版本 ≥ 2024.3.1
• JDK 必须是 17
• 改阿里云镜像（见 1.8 节）
• File → Invalidate Caches... → 勾全部 → 重启

Q4：Build APK 报错

• 找不到 dcloud_control.xml → 见 1.6 节手动创建
• 找不到 www 目录 → 见 1.7 节手动创建
• 找不到前端资源 → 跑一遍 npm run sync-android
• 签名相关错误 → 用 Build → Build APK(s)（默认 debug 签名），别走 Generate Signed Bundle / APK

Q5：APP 启动报"未配置 appkey"

按 SDK 版本分别处理：

SDK 3.9+（推荐）

dcloud_control.xml 里加 appkey 属性：

<app appid="__UNI__abcd1234" 
     appver="1.0.0"
     appkey="您的AppKey"/>

SDK 3.0~3.8

改 app/src/main/AndroidManifest.xml，在 <application> 里加：

<meta-data
    android:name="dcloud_appkey"
    android:value="您的AppKey" />

检查清单

项	正确做法
AppKey 来源	DCloud 后台 → 我的应用 → 基础信息（点"显示"）
AppKey 格式	小写十六进制，别带前后空格/换行
AppID 一致性	manifest.json 和 dcloud_control.xml 必须同一个
包名一致	DCloud 后台设置的包名 = build.gradle 里 applicationId
旧 APP 残留	adb uninstall 包名 卸干净再装新 APK

Q5：微信传 APK 文件名变成 .apk.1

方法	操作
当前救回	长按 → 重命名 → 删掉 .1
下次加尾巴	改名 每日打卡.apk.png 或 每日打卡.apk.
邮件附件	不被改
网盘分享	百度/阿里云盘/微云/文叔叔

---

7. 进阶：正式发布用 release 签名

⚠️ 仅当要上架应用商店或给真用户长期使用时才做这一步。
.jks 文件 + 密码一旦丢了，这个 APP 就再也升不了级了！

7.1 生成 keystore

1. Build → Generate Signed Bundle / APK
2. 选 APK → Next
3. 点 Create new...
4. 填写：

字段	示例
Key store path	D:/keys/tiantiandaka-release.jks
Password	设强密码，记下来
Key alias	tiantiandaka
Validity	25 年
姓名/组织	随意

5. 点 OK → Next → 选 release → Finish

7.2 产物路径

app/build/outputs/apk/release/app-release.apk

7.3 保管 keystore

• 备份到网盘 + 至少 2 个本地位置
• 团队里至少 2 个人知道密码
• 离职交接时作为公司资产移交

---

8. 进阶：wgt 热更新（改前端不用重打 APK）

用户已经装过 APP 后，只改了前端代码，不用重打 APK，用 wgt 资源包远程热更新。

详见 APK打包文档.md 第七章。

骨架代码（放在 frontend/src/App.vue 的 onLaunch）：

import { checkUpdate } from '@/utils/update'

onLaunch(() => {
  checkUpdate()  // 后端返回 { wgtUrl, version }
})

---

最后更新：2026-09-12
维护者：阿木
配套文档：APK打包文档.md