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+，其余的全部自动搞定：

换一台机器部署？直接把整个项目目录拷过去，一行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 权限：

不需要再手写 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}/ │ └──────────────────────────────────────────────┘

技术选型：

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

环境变量（按需配置）

使用流程详解

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。

为什么要用这个项目？

对比官方云打包

对比手动离线打包

适用场景

1. 个人开发者——再也不用打开 HBuilderX 点半天按钮了，浏览器即打包
2. 小团队——部署在内网服务器上，所有人共用一套打包环境
3. CI/CD 集成——结合 Jenkins / GitHub Actions / GitLab CI，代码提交自动出包
4. 企业内网——代码不出内网，安全合规
5. 多项目多版本管理——不同项目可以绑定不同版本的 UniApp SDK，互不干扰

未来规划

• 支持 uni-app cli 源码打包
• 支持 uni-app x (Kotlin 原生) 打包
• 支持 iOS IPA 打包（需 macOS 构建机）
• Docker 一键部署镜像
• 构建队列与优先级调度
• Webhook 通知
• 前端界面重构

结语

这个项目的初心很简单：让 uni-app 打包这件事变得像呼吸一样自然。

作为 uni-app 开发者，我们不应该把时间花在折腾打包环境上。写代码才是我们的核心价值。把打包交给平台，把精力还给开发。

如果你觉得这个项目有用，欢迎 Star、Fork、提 Issue、提 PR。也欢迎在评论区交流你的打包故事和需求。

GitHub: https://github.com/zimoyin/uniapp-cloud-build