一、背景
-
背景：
在当前的跨平台移动应用开发中，使用 uni-app 框架配合 HBuilderX 进行开发已成为高效的主流选择之一。然而，随着项目迭代频率加快、多环境交付需求增多，依赖 HBuilderX 图形界面进行手动打包的操作模式，暴露出效率低下、流程繁琐、易出错、不利于持续集成/持续交付 (CI/CD) 等问题。
-
核心需求：
为实现研发流程的自动化与规范化，本项目旨在建立一套稳定、可靠、可重复执行的 APP 自动打包流水
全平台打包：能够通过单次命令或触发，自动完成 iOS 和 Android 双平台应用包的构建。
环境隔离：支持为开发、测试、生产等不同环境，自动化构建对应配置的应用包。
集成与自动化：能够无缝集成到现有的 Git 代码仓库、Jenkins/GitLab CI 等 CI/CD 工具链中，实现代码提交后自动构建。
可配置与可维护：打包所需的证书、配置参数应代码化、模块化，方便团队协作与版本管理。
效率与可靠性：显著提升打包速度，减少人工干预，保证每次构建产物的可靠性与一致性
二、技术方案选型与评估
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 核心工具与环境准备
安装 HBuilderX：确保在构建服务器或本地用于自动化的机器上，安装与项目匹配版本的 HBuilderX。
获取 hbuilderx-cli：hbuilderx-cli 工具位于 HBuilderX 安装目录下。
Windows: {HBuilderX安装目录}/cli.exe
macOS/Linux: {HBuilderX安装目录}/cli
为方便使用，需要将 cli 工具所在目录添加到系统的 PATH 环境变量中（重要）。
重中之重：配置cli环境变量（所有的cli命令打包，都基于cli命令可以正常执行）
也可以查看我另一边cli安装步骤细节截图： https://blog.csdn.net/weixin_63515766/article/details/157427569
在使用命令前，需确保已将 HBuilderX 的 CLI 路径添加到系统环境变量中。
1. 正确的打开方式
你必须通过“终端”（Terminal）或“命令提示符”（CMD）来运行它：
2. 必须配置环境变量（推荐）
为了在任何地方都能使用 cli 命令，而不是每次都去找安装目录，请务必配置环境变量：
