hbuilerx下如何打包安卓的APK包

APK 打包文档

本文档整理 每日打卡 APP 的 Android 端打包流程，含 CLI 本地编译、HBuilderX 云打包、免费离线打包三种方案，以及踩坑合集。

一、项目技术栈

端	技术
前端	uni-app (Vue 3 + TypeScript) + Vite
后端	Spring Boot 3 + MyBatis + MySQL 8 + JWT
编译产物	`frontend/dist/build/app/`

⚠️ uni-app CLI 的一个反直觉点：build -p app-android 的产物目录是 dist/build/app/，不是 dist/build/app-android/。以实际目录为准。

二、准备工作（首次打包必做）

2.1 申请 DCloud 账号 & 实名

打开 https://dev.dcloud.net.cn/ 注册账号
完成 实名认证（上传身份证，未实名无法创建应用）
左菜单 → 我的应用 → 新建应用
填写：
- 应用名称：每日打卡
- 应用类型：uni-app
创建完成后，进入应用详情，基础信息 页面有一行 AppID，格式如 __UNI__abcd1234

2.2 写入 `src/manifest.json`

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

"appid": "",

改为：

"appid": "__UNI__abcd1234",

⚠️ 改的是 src/ 下的源码 manifest，不是 dist/build/app/ 下的产物 manifest（产物会被下次 build 覆盖）。

2.3 确认 `src/utils/request.ts` 后端地址

// 本机调试（电脑和手机同一 WiFi）
const BASE_URL = 'http://192.168.x.x:8080/api'
// 真机 USB 调试（adb reverse 把 8080 映射到手机）
const BASE_URL = 'http://localhost:8080/api'
// 线上
const BASE_URL = 'https://api.yourdomain.com/api'

三、CLI 本地编译（产出 wgt 资源包）

3.1 命令

cd frontend
npm install              # 首次或依赖变更时跑
npm run build:app-android

3.2 产物路径

frontend/dist/build/app/
├── manifest.json
├── app-service.js
├── app.css
├── app-config.js
├── pages/
└── __uniapp*.{html,js,png}

这一步只是把 Vue/TS 代码编译成 uni-app 运行时能加载的静态资源 + manifest，还不是 APK。

3.3 踩坑

现象	原因	解决
`'uni' 不是内部或外部命令`	`node_modules` 没装全	跑 `npm install` 重装
`cd: frontend: No such file or directory`	shell 工作目录已在 frontend 里	删掉 `cd frontend` 直接跑 npm 命令
编译后端口 5173 仍被占	dev server 还在跑	`taskkill /PID <pid> /F`，或另开终端

四、HBuilderX 云打包（最快上手，但要钱）

适合：临时打个测试 APK、不想折腾 Android Studio。每账号每天有少量免费次数（具体看 DCloud 当下政策）。

4.1 安装 HBuilderX

下载标准版：https://www.dcloud.io/hbuilderx.html

4.2 导入项目

启动 HBuilderX
文件 → 导入 → 从本地目录导入
选 frontend/dist/build/app/
左侧项目树点开 manifest.json，图形化界面里能看到 AppID 已自动填好

4.3 云打包

菜单 发行 → 原生 APP-云打包
配置：
- 平台：Android
- 证书：DCloud 公共测试证书（白嫖，仅测试用）
- 包名：默认读 manifest，不要乱改
- ABI：只勾 arm64-v8a（省一半体积，构建快一倍）
点提交，等 5–10 分钟
底部控制台会弹下载链接，下载下来就是 APK

4.4 拿到 APK 后

重命名为 每日打卡.apk（不要带中文路径）
传到手机：
- 微信 / QQ / 钉钉：会自动改成 xxx.apk.1，见第六章
- 推荐方式：邮件附件 / 百度网盘 / 文叔叔
手机上点击 APK → 允许安装未知来源 → 完成

五、离线打包（完全免费，强烈推荐）

一次性配置 ~2 小时，之后每次改前端代码 30 秒出 APK，不用排队不用花钱。

5.1 下载 Android 离线 SDK

打开 https://nativesupport.dcloud.net.cn/AppDocs/SDK包下载
找一个版本号匹配 HBuilderX 的（比如 Android-SDK@3.94）
下载后解压，得到 HBuilder-Integrate-AS 目录

5.2 配置 Android Studio 工程

用 Android Studio 打开 HBuilder-Integrate-AS
等待 Gradle sync 完成（首次很慢）

找到 app/src/main/assets/data/dcloud_control.xml，把 AppID 填进去：

<dcloud_control>
    <app appid="__UNI__abcd1234" appver="1.0.0"/>
</dcloud_control>

5.3 同步 wgt 资源

每次前端代码改完，跑完 CLI 编译后，把整个 frontend/dist/build/app/ 内容覆盖到：

HBuilder-Integrate-AS/app/src/main/assets/apps/__UNI__abcd1234/www/

（appid 那个目录名就是你的 AppID，把 __UNI__abcd1234 替换成实际的）

5.4 本地出 APK

Android Studio 顶部菜单 Build → Generate Signed Bundle / APK
选 APK
选 debug 签名（开发测试用，免去 keystore 配置）
选 release 或 debug build variant
完事后 APK 在 app/build/outputs/apk/{variant}/ 下

5.5 自动化建议

把"CLI 编译 + 拷贝资源"做成一个 npm script：

// frontend/package.json
"scripts": {
  "sync-android": "node scripts/sync-android.js"
}

// frontend/scripts/sync-android.js
const fs = require('fs-extra');
const path = require('path');

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

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

之后流程就是：

npm run build:app-android
npm run sync-android
# 然后 Android Studio 点一下 Build 按钮

六、常见问题

6.1 微信传 APK 文件名变成 `.apk.1`

原因：微信/QQ/钉钉按后缀名识别可执行文件，自动改名阻止传播。

解决：

方法	操作
当前文件救回	长按 → 重命名 → 把 `.1` 删掉 → 改成 `每日打卡.apk`
下次加尾巴	发之前改名 `每日打卡.apk.png` 或 `每日打卡.apk.`（末尾多一个点）→ 收到后改回 `.apk`
打包成 zip	`右键 → 压缩` → 收到后解压出 apk
邮件附件	给自己发邮件，附件不会被改
网盘	百度网盘 / 阿里云盘 / 微云 / 文叔叔，分享下载链接

6.2 `项目的AppID不能为空`

src/manifest.json 第 3 行 "appid": "" 没填，见第二章 2.2 节。

6.3 装上 APP 后请求后端失败

网络异常 → 检查 utils/request.ts 的 BASE_URL，真机调试不能用 localhost，改成电脑局域网 IP
手机和电脑不同 WiFi → 改连同一 WiFi，或用 adb reverse tcp:8080 tcp:8080 走 USB 隧道
后端没起 → cd backend && mvn spring-boot:run

6.4 启动白屏

99% 是 AppID 没配或配错，HBuilderX 编译时 manifest.json 里的 appid 必须和 DCloud 后台一致
少部分情况是后端接口不通，登录页能进但首页 fetch 不到数据一直 loading

6.5 离线打包 Gradle 同步失败

检查 Android Studio 版本 ≥ Hedgehog (2023.1)
JDK 用 17（项目 pom.xml 里 <java.version>17</java.version>）
gradle-wrapper.properties 里 distributionUrl 国内可能下不动 → 改用阿里云镜像：https://mirrors.aliyun.com/macports/distfiles/gradle/gradle-8.x-all.zip

七、wgt 热更新（改前端代码不用重打 APK）

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

7.1 适用场景

改 UI、文案、样式
加新页面、调接口
修复前端 bug

不适用：改 manifest、加新原生模块（如推送、支付）、动权限

7.2 流程

前端改完后跑 npm run build:app-android，产物里会自动生成 __UNI__abcd1234.wgt
把 wgt 传到你的 CDN / OSS
APP 启动时调后端接口拿最新版本号，比对本地版本决定是否下载
下载后用 plus.runtime.install() 静默安装，下次启动生效

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

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

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

八、速查表

想做的事	命令 / 路径
首次拉代码装依赖	`cd frontend && npm install`
编译 Android wgt	`npm run build:app-android`
编译产物	`frontend/dist/build/app/`
启动后端	`cd backend && mvn spring-boot:run`
启动前端 H5 调试	`npm run dev:h5` → http://localhost:5173
申请 AppID	https://dev.dcloud.net.cn/
Android 离线 SDK	https://nativesupport.dcloud.net.cn/
查端口占用	`netstat -ano \| grep :8080`
杀进程	`taskkill /PID <pid> /F`

最后更新：2026-09-10
维护者：阿木

posted @ 2026-09-13 09:05 amu2018 阅读(65) 评论(0) 收藏举报

刷新页面返回顶部

阿木2018

hbuilerx下如何打包安卓的APK包

APK 打包文档

一、项目技术栈

二、准备工作（首次打包必做）

2.1 申请 DCloud 账号 & 实名

2.2 写入 `src/manifest.json`

2.3 确认 `src/utils/request.ts` 后端地址

三、CLI 本地编译（产出 wgt 资源包）

3.1 命令

3.2 产物路径

3.3 踩坑

四、HBuilderX 云打包（最快上手，但要钱）

4.1 安装 HBuilderX

4.2 导入项目

4.3 云打包

4.4 拿到 APK 后

五、离线打包（完全免费，强烈推荐）

5.1 下载 Android 离线 SDK

5.2 配置 Android Studio 工程

5.3 同步 wgt 资源

5.4 本地出 APK

5.5 自动化建议

六、常见问题

6.1 微信传 APK 文件名变成 `.apk.1`

6.2 `项目的AppID不能为空`

6.3 装上 APP 后请求后端失败

6.4 启动白屏

6.5 离线打包 Gradle 同步失败

七、wgt 热更新（改前端代码不用重打 APK）

7.1 适用场景

7.2 流程

八、速查表

公告

阿木2018

hbuilerx下如何打包安卓的APK包

APK 打包文档

一、项目技术栈

二、准备工作（首次打包必做）

2.1 申请 DCloud 账号 & 实名

2.2 写入 src/manifest.json

2.3 确认 src/utils/request.ts 后端地址

三、CLI 本地编译（产出 wgt 资源包）

3.1 命令

3.2 产物路径

3.3 踩坑

四、HBuilderX 云打包（最快上手，但要钱）

4.1 安装 HBuilderX

4.2 导入项目

4.3 云打包

4.4 拿到 APK 后

五、离线打包（完全免费，强烈推荐）

5.1 下载 Android 离线 SDK

5.2 配置 Android Studio 工程

5.3 同步 wgt 资源

5.4 本地出 APK

5.5 自动化建议

六、常见问题

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

6.2 项目的AppID不能为空

6.3 装上 APP 后请求后端失败

6.4 启动白屏

6.5 离线打包 Gradle 同步失败

七、wgt 热更新（改前端代码不用重打 APK）

7.1 适用场景

7.2 流程

八、速查表

公告

2.2 写入 `src/manifest.json`

2.3 确认 `src/utils/request.ts` 后端地址

6.1 微信传 APK 文件名变成 `.apk.1`

6.2 `项目的AppID不能为空`