uniapp-cloud-build：自动化 uni-app 云打包，解放你的双手-尧图网络科技

前言

作为一名 uni-app 开发者，你是否经历过这些痛苦？

每次打 APK 包都要打开 HBuilderX，切到发行菜单，点半天按钮
团队协作时，每个人的 Android 签名、SDK 配置各不一样，打包环境一团乱
CI/CD 流水线想集成自动打包，却发现官方云打包有限制，离线打包又要在每台机器上装 Android Studio
换了台电脑，又要重装 JDK、Android SDK、Gradle 一大堆工具链

如果你有以上任一痛点，那这个项目就是为你准备的。

uniapp-cloud-build是一个开源的 uni-app APK 云打包平台——只需上传源码或 IR 包，在 Web 界面上点几下鼠标，APK 就自动打好了。全程无需 Android Studio，工具链自包含，不污染系统环境。

GitHub 地址：https://github.com/zimoyin/uniapp-cloud-build（开源免费，欢迎 Star）

项目定位：一句话说清楚

uni-app APK 离线云打包的 Web 管理平台——把你的打包环境搬上浏览器，让团队所有人都能用同一套环境、同一套配置来打包，彻底告别"我这能打你那不行"的玄学问题。

核心功能

1. 云端打包，告别本地环境

支持两种输入方式：

源码模式：直接上传 uni-app 项目的src/目录
IR 包模式：上传 HBuilderX 发行菜单生成的"本地打包 App 资源"包（__UNI__xxxxx目录打个 zip）

平台会自动完成 8 阶段构建流水线：

上传源码/IR → 校验 Manifest → 环境检测 → 创建工作空间 → 部署资源 → 同步插件 → 写入工程配置 → Gradle 编译 → 收集 APK

2. 自包含工具链，零环境依赖

这是本项目最大的亮点。跑这个服务，你只需要一个 JDK 17+，其余的全部自动搞定：

工具	自动管理方式
JDK 17/21	自动下载到`./cache/jdk/`，构建时按需选用
Android SDK	自动下载 API 21~36 任意版本到`./cache/android-sdk/`
Gradle	自动下载 6.3~8.12 任意版本到`./cache/gradle/`
UniApp SDK	Web 界面手动上传离线包到`./cache/sdk/`，支持版本管理

换一台机器部署？直接把整个项目目录拷过去，一行java -jar就起来了，不用装任何东西。

3. Web 管理界面，开箱即用

浏览器打开http://localhost:8080，注册即用。你可以：

管理多个应用——每个应用独立的工作空间和构建历史
配置签名——上传 keystore，自动写入 signingConfig
管理 SDK 模块——勾选地图、推送、支付等 20+ UniApp SDK 模块，自动注入 Android 权限和硬件特性声明
上传插件——按应用上传.aar/.jar/.zip原生插件
触发构建——选择 JDK 版本、Gradle 版本、Android API 版本，一键开始
下载 APK——构建完成后浏览器直接下载

4. 多用户系统，团队协作利器

内置完整的用户体系：

注册/登录——每个人有自己的独立工作空间
三级角色——普通用户、管理员、超级管理员，权限分明
构建历史——每个人的构建记录、日志、产物可追溯

团队里只要部署一台服务器，所有人都能用浏览器打包，再也不用各自折腾环境。

5. CI/CD 友好，一行脚本接入流水线

平台提供"云端脚本"功能——在 Web 界面生成嵌入 Token 的 Shell/Batch 脚本，直接放进你的 CI/CD 流水线里：

# 登录获取 Tokencurl-XPOST http://your-server:8080/api/auth/login\-H'Content-Type: application/json'\-d'{"username":"ci-bot","password":"xxx","fingerprint":"ci"}'# 触发构建curl-XPOST http://your-server:8080/api/v1/build/team/app1/build\-H'Authorization: Bearer <token>'\-F'file=@project.zip'\-F'config={"compileSdk":35,"gradleVersion":"8.11.1"}'# 下载 APKcurl-Ohttp://your-server:8080/api/v1/download/<taskId>\-H'Authorization: Bearer <token>'

支持 WebSocket 实时推送构建日志，你可以看到每一行 Gradle 输出，就像在本地打包一样。

6. 20+ SDK 模块，自动权限映射

内置 UniApp SDK 模块识别引擎，根据manifest.json中的模块名自动注入 Android 权限：

模块	自动配置
地图 (Maps)	`ACCESS_FINE_LOCATION`,`ACCESS_COARSE_LOCATION`
相机 (Camera)	`CAMERA`
推送 (Push)	各厂商推送权限 + Receiver
支付 (Payment)	微信/支付宝相关权限
蓝牙 (Bluetooth)	`BLUETOOTH`,`BLUETOOTH_ADMIN`
…	共 20+ 模块自动配置

不需要再手写 AndroidManifest.xml 里的权限声明了。

技术架构

┌──────────────────────────────────────────────┐ │ Browser │ │ (Web UI + Swagger API Docs) │ └──────────────────┬───────────────────────────┘ │ HTTP / WebSocket ┌──────────────────▼───────────────────────────┐ │ Spring Boot 3.4.5 │ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │ │ Auth │ │ Build │ │ Toolchain │ │ │ │ Controller│ │ Controller│ │ Controllers │ │ │ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │ │ │ │ │ │ │ ┌────▼─────────────▼───────────────▼───────┐ │ │ │ BuildPipeline │ │ │ │ (8-phase: Validate → Collect APK) │ │ │ └────────────────┬────────────────────────┘ │ │ │ │ │ ┌────────────────▼────────────────────────┐ │ │ │ Toolchain Manager │ │ │ │ JDK | Android SDK | Gradle | UniApp SDK │ │ │ └─────────────────────────────────────────┘ │ └──────────────────┬───────────────────────────┘ │ ┌──────────────────▼───────────────────────────┐ │ File System │ │ cache/jdk/ cache/android-sdk/ │ │ cache/gradle/ cache/sdk/ cache/plugins/ │ │ cache/pkg/{user}/{app}/ │ └──────────────────────────────────────────────┘

技术选型：

层面	技术	说明
语言	Kotlin 2.3.21	简洁、安全、与 Java 完美互操作
框架	Spring Boot 3.4.5	企业级后端框架
安全	Spring Security	无状态 Bearer Token 认证
实时通信	Spring WebSocket	构建日志实时推送
并发	Kotlin 协程 + 虚拟线程	高并发构建任务
API 文档	springdoc-openapi	Swagger UI 自动生成
构建工具	Gradle Kotlin DSL	项目自身构建（含 Wrapper）
JVM 目标	JDK 17	兼容 JDK 25 源码编译

62 个 Kotlin 源文件，架构清晰：

controller/— 10 个 REST 控制器（认证、构建、JDK、Gradle、Android SDK、UniApp SDK、插件、下载、管理、系统）
service/— 13 个服务类，核心业务逻辑
pkg/phase/— 8 个构建阶段，管道模式设计
model/— 数据传输对象和领域模型
config/— Spring 安全、异步、WebSocket、定时清理等配置

快速开始

环境要求

只需要 JDK 17+，其余全部自动下载。

三步跑起来

# 1. 克隆项目gitclone https://github.com/zimoyin/uniapp-cloud-build.gitcduniapp-cloud-build# 2. 启动服务（Linux/macOS）chmod+x gradlew ./gradlew bootRun# Windowsgradlew.bat bootRun

浏览器打开http://localhost:8080，注册账号，上传 UniApp SDK 离线包，然后就可以开始打包了。

JAR 部署

# 打包./gradlew bootJar# 前台运行java-Xms512m-Xmx512m-jarbuild/libs/uniapp-apk-builder-1.0.0.jar# 后台运行（Linux）shapp.sh start-d

环境变量（按需配置）

变量	默认值	说明
`APP_PORT`	`8080`	服务端口
`WORKSPACE_ROOT`	`./cache`	缓存与工作空间根目录
`GRADLE_MIRROR`	`mirrors.cloud.tencent.com/gradle`	Gradle 下载镜像（国内加速）
`AES_KEY`	随机生成	配置加密密钥
`LOG_DIR`	`./cache/logs`	日志目录

使用流程详解

Step 1：上传 UniApp SDK

首先需要上传一个 UniApp 离线 SDK 包。去 DCloud 官方下载 Android 离线 SDK，在 Web 界面的"UniApp SDK 管理"页面上传并命名版本。

Step 2：创建应用

在 Web 界面创建一个应用，填写包名、应用名等基本信息。

Step 3：配置签名

上传你的 keystore 文件，填写别名和密码。平台会自动在构建时配置签名。

Step 4：上传代码

将你的 uni-app 项目源码（src/目录）打包成 zip，或使用 HBuilderX 发行菜单生成 IR 包后打包成 zip，上传到应用中。

Step 5：选择 SDK 模块

勾选你的应用用到的 UniApp 模块（地图、推送、支付等），平台会自动处理 Android 权限和依赖。

Step 6：开始构建

选择构建参数（JDK 版本、Gradle 版本、Android API 版本），点击"开始构建"。构建日志通过 WebSocket 实时显示。

Step 7：下载 APK

构建完成后，在构建历史中直接下载 APK。

为什么要用这个项目？

对比官方云打包

维度	DCloud 官方云打包	uniapp-cloud-build
打包次数	有限制（免费套餐每日限量）	无限制
构建速度	排队等待	本地/内网，即点即打
离线环境	不支持	支持（局域网部署）
数据安全	代码上传到第三方服务器	数据完全在自己手里
SDK 版本	跟随官方更新	自由选择/管理版本

对比手动离线打包

维度	手动离线打包	uniapp-cloud-build
环境搭建	装 JDK + Android Studio + SDK + Gradle	一键部署
团队协作	每人自己搭环境，配置不一致	统一环境，Web 操作
CI/CD	需要在每台 CI 机器上装全套工具	一行 curl 搞定
新人上手	半天起步	打开浏览器就行