使用HBuilderX 自带hbuilderx-cli 自动化打包uniapp的移动端app（Android，iOS）

一、背景

• 背景：

在当前的跨平台移动应用开发中，使用 uni-app 框架配合 HBuilderX 进行开发已成为高效的主流选择之一。然而，随着项目迭代频率加快、多环境交付需求增多，依赖 HBuilderX 图形界面进行手动打包的操作模式，暴露出效率低下、流程繁琐、易出错、不利于持续集成/持续交付 (CI/CD) 等问题。

• 核心需求：

为实现研发流程的自动化与规范化，本项目旨在建立一套稳定、可靠、可重复执行的 APP 自动打包流水

1. 全平台打包：能够通过单次命令或触发，自动完成 iOS 和 Android 双平台应用包的构建。

2. 环境隔离：支持为开发、测试、生产等不同环境，自动化构建对应配置的应用包。

3. 集成与自动化：能够无缝集成到现有的 Git 代码仓库、Jenkins/GitLab CI 等 CI/CD 工具链中，实现代码提交后自动构建。

4. 可配置与可维护：打包所需的证书、配置参数应代码化、模块化，方便团队协作与版本管理。

5. 效率与可靠性：显著提升打包速度，减少人工干预，保证每次构建产物的可靠性与一致性

二、技术方案选型与评估

2.1 可选方案对比

|---------------------|----------------------------|----------------------------------------|------------------------------------|-------------|
| 方案 | 核心工具 | 优点 | 缺点/挑战 | 推荐度 |
| 方案一：官方 CLI 工具链 | hbuilderx-cli (官方) + 自定义脚本 | 官方支持，兼容性最好；功能稳定；直接调用 HBuilderX 原生打包能力。 | 官方 CLI 文档相对精简；部分高级配置需研究。 | ★★★★★ (首选) |
| 方案二：社区增强 CLI 工具 | hb-cli-ugreen 等第三方 npm 包 | 对官方 CLI 进行了封装，可能提供更易用的配置项和额外功能（如自动上传）。 | 依赖社区维护，长期稳定性与更新时效性存疑；本质仍是封装官方 CLI。 | ★★★☆☆ (备选) |
| 方案三：HBuilderX 插件自动化 | 基于 HBuilderX 插件 API 开发 | 可深度集成到 HBuilderX IDE 中，实现图形化一键操作。 | 开发成本高；无法脱离 IDE 运行，不适用于 CI/CD 无头环境。 | ★☆☆☆☆ (不适用) |

综合评估，推荐采用方案一：基于官方 hbuilderx-cli 的自定义脚本方案。

• 可靠性：官方工具能确保与 HBuilderX 核心打包引擎的完美同步，避免因第三方工具兼容性问题导致的打包失败。

• 可维护性：直接使用官方接口，技术栈更纯粹，问题更易追溯和解决。

• 灵活性：通过编写 Shell/Node.js 脚本，可以完全自定义打包前、中、后的所有流程，灵活集成到任意自动化系统中。

三、 基于 hbuilderx-cli 的可执行技术方案

3.1 核心工具与环境准备

1. 安装 HBuilderX：确保在构建服务器或本地用于自动化的机器上，安装与项目匹配版本的 HBuilderX。

2. 获取 hbuilderx-cli：hbuilderx-cli 工具位于 HBuilderX 安装目录下。

   1. Windows: {HBuilderX安装目录}/cli.exe

   2. macOS/Linux: {HBuilderX安装目录}/cli

   3. 为方便使用，需要将 cli 工具所在目录添加到系统的 PATH 环境变量 中（重要）。

重中之重：配置cli环境变量（所有的cli命令打包，都基于cli命令可以正常执行）

在使用命令前，需确保已将 HBuilderX 的 CLI 路径添加到系统环境变量中。

1. 正确的打开方式

你必须通过"终端"（Terminal）或"命令提示符"（CMD）来运行它：

1. 在 HBuilderX 安装目录的 cli.exe 所在文件夹中，按住 Shift 键 + 鼠标右键。

2. 选择"在此处打开 PowerShell 窗口 "或"在此处打开命令行窗口"。

3. 在弹出的窗口中输入 ./cli.exe --version。如果看到版本号，说明工具正常。

4. 必须配置环境变量（推荐）

为了在任何地方都能使用 cli 命令，而不是每次都去找安装目录，请务必配置环境变量：

1. 右键"此电脑" -> 属性 -> 高级系统设置 -> 环境变量。

2. 在"系统变量"中找到 Path，点击编辑。

3. 点击"新建"，将 cli.exe 所在的目录路径 （例如 D:\HBuilderX\bin 或 D:\HBuilderX，取决于你的安装位置）粘贴进去。

4. 保存后，重新打开一个新的 CMD 窗口，输入 cli 即可使用。

5. 如果在终端运行提示"权限不足"或"找不到命令"

• 权限问题：请尝试以"管理员身份"运行 PowerShell。
• 路径含有空格 ：如果你的 HBuilderX 安装路径包含空格（如 C:\Program Files\...），在命令行中调用时需要给路径加引号。
• HBuilderX 未启动：部分 CLI 指令依赖 HBuilderX 后台服务。如果报错，请确保 HBuilderX 编辑器已经处于打开状态。

四、操作步骤

整体步骤概览：

1. 安装HBuilderX，并配置环境变量。

2. 在项目中配置打包所需的参数（如应用名称、图标、证书等）。

3. 可以结合Windows计划任务或手动运行脚本实现自动化。

操作步骤可分为两种：

方法一： cli 命令行打包：

官网的cli命令文档： https://hx.dcloud.net.cn/cli/pack

1.使用命令直接打包，打包的包会存在对应的位置，Android会存在项目当中的unpackage/release中，但是iOS需要手动下载链接，如果没有弹出下载链接，可以手动点击发行-查看打包状态

相关cli命令参数：

|---------------------------|-------------------------------------------------------------------------------|
| 参数名称 | 描述 |
| --help | 打包命令帮助 |
| --config | 配置文件绝对路径，配置文件配置，参考配置文件 |
| --project | HBuilder X 里导入的项目名或绝对路径 |
| --platform | 配打包平台,默认值 android,取值有"android","ios"如果要打多个逗号隔开 |
| --iscustom | 是否使用自定义基座 默认值 false, true 自定义基座 false 自定义证书 |
| --safemode | 打包方式是否为安心打包,默认值 false,true 安心打包,false 传统打包 |
| --isconfusion | 是否对配置的 js/nvue 文件进行原生混淆，true 打开 false 关闭 |
| --splashads | 开屏广告,默认值 false, true 打开 false 关闭 |
| --rpads | 悬浮红包广告,默认值 false, true 打开 false 关闭 |
| --pushads | push 广告,默认值 false, true 打开 false 关闭 |
| --exchange | 加入换量联盟,默认值 false, true 加入 false 不加入 |
| --android.packagename | 安卓包名，打安卓包填写 |
| --android.androidpacktype | 安卓打包类型 默认值 0,0 使用自有证书 1 使用公共证书 2 使用 DCloud 老版证书 |
| --android.certalias | 安卓打包证书别名,自有证书打包填写的参数 |
| --android.certfile | 安卓打包证书文件路径,自有证书打包填写的参数 |
| --android.certpassword | 安卓打包证书密码,自有证书打包填写的参数 |
| --android.storepassword | 安卓打包证书库密码（HBuilderx4.41 支持）,自有证书打包填写的参数 |
| --android.channels | 安卓平台要打的渠道包,取值有"google","yyb","360","huawei","xiaomi","oppo","vivo"，如果要打多个逗号隔开 |
| --ios.bundle | iOS appid 打 ios 包填写 |
| --ios.supporteddevice | iOS 打包支持的设备类型,默认值 iPhone 值有"iPhone","iPad" 如果要打多个逗号隔开打包平台 |
| --ios.isprisonbreak | iOS 打包是否打越狱包,true 打越狱包,false 正式包。HBuilderX 3.2.3+版本起，不再支持构建越狱包。 |
| --ios.profile | iOS 使用自定义证书打包的 profile 文件路径 |
| --ios.certfile | iOS 使用自定义证书打包的 p12 文件路径 |
| --ios.certpassword | iOS 使用自定义证书打包的证书密码 |

使用示例：

# 通过配置文件打包cli pack --config 配置文件 # Android打包：项目名称（apps）、传统打包、包名（io.test)、打包证书（自有证书、别名：testalias、密码123456）cli pack --project apps --platform android --safemode false --android.packagename io.test --android.androidpacktype 0 --android.certalias testalias --android.certfile /Users/hx/Desktop/cert/jdk13/test.key --android.certpassword 123456 --android.storepassword 123456 # iOS打包cli pack --project 项目名称 --platform ios --safemode false --iscustom true --ios.bundle 包名 --ios.supporteddevice iPhone,iPad --ios.isprisonbreak false --ios.profile profile文件路径 --ios.certfile p12文件路径 --ios.certpassword 证书密码

方法二：自动化脚本打包

这个方法还是基于上述方法，只不过把命令都放在脚本里，然后直接配置指令执行脚本

1.环境配置

2.创建自动化脚本 build.js

（乱码先执行chcp 65001）

脚本有需要我再更新

3.配置 package.json 快捷指令

4.执行打包

项目配置自动化

自动化打包的前提是项目配置的代码化。uni-app 项目需重点关注以下文件：

|---------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 配置文件 | 自动化关键 | 建议操作 |
| manifest.json | 应用基础配置、各平台设置 | 1. 将不同环境的 appid、版本号等抽离为模板变量。 2. 使用构建脚本在打包前，根据环境动态替换/生成最终文件。 |
| 证书与私钥文件 | 打包签名安全 | 1.安全存储：将 .keystore (Android)、.p12 和 .mobileprovision (iOS) 文件存储在安全的凭据管理系统（如 GitLab CI Variables, Jenkins Credentials）中，切勿提交到 Git。 2. 构建时注入：在 CI/CD 流水线中，于打包前将证书文件动态写入到项目指定目录或构建服务器的临时位置。 |

团队协作与维护建议

4.1 配置文件管理

• 模板化：在仓库中维护 manifest.json，其中版本号、应用名称等使用占位符（如 {``{version}}）。

4.2 证书安全管理

• 权限控制：只有项目负责人或运维人员有权访问和维护 CI/CD 系统中的证书变量。

• 更新机制：建立证书过期预警流程，在证书过期前及时更新 CI/CD 变量中的文件。

后续优化方向

1. 构建缓存：研究对 node_modules、unpackage 等目录进行缓存，加速后续构建。

2. 质量门禁：在打包流程中集成代码检查、单元测试、安全扫描等。

3. 自动发布：打包成功后，脚本可自动将 APK/IPA 上传至内测分发平台（如蒲公英、fir.im）或应用商店。

4. 多环境差异化构建：完善脚本，支持根据分支或标签，一键构建出不同后端 API 地址、应用标识的安装包。

---

结论：采用基于官方 hbuilderx-cli 的自动化打包方案，技术上成熟可靠，能有效满足项目对于 iOS 和 Android 双平台、多环境的自动化构建需求。通过将配置代码化、证书安全化管理，并集成到现代 CI/CD 流程中，可以极大提升团队交付效率与应用质量的一致性。建议从小范围试点开始，逐步完善流程。