Cocos Creator 到 OpenHarmony：自动化构建 HAP 包全流程解析

1. 从“点按钮”到“跑命令”，这条链路自动化到底图什么

这半年我一直在折腾一件事：把Cocos Creator工程构建成OpenHarmony应用的流程，从每天手动打开编辑器、点构建面板、填参数，改成一条命令触发、全自动出包的流水线。最初只是嫌麻烦，后来发现手动构建真正的问题不是慢，而是不可靠——同样的参数，今天能出包，明天换一台机器就失败；同一个版本，上午打的包和下午打的包，安装行为都能不一样。

先说结论：如果你的团队还在用“人肉点按钮”的方式出 OpenHarmony 包，我强烈建议你把这件事当成一个正儿八经的工程问题来解决，而不是靠“记得盯一下”来兜底。自动化构建换来的不光是省下那十几分钟，更重要的是让每一次出包都可复现、可追踪、可回溯。

1.1 手动打包的一天有多痛苦

我经历过一段相当原始的阶段。那时候每次要给测试提包，流程是固定的：打开 Cocos Creator，打开项目工程，等编辑器加载完成；打开构建面板，选择 OpenHarmony 平台，填写包名、版本号、构建目标；点构建，等进度条走完；构建完成后再打开 DevEco Studio 去打开生成好的工程，等 hvigor 同步依赖、编译；编译通过后再调签名工具，把 HAP 包签上名；最后用命令行 adb 装到开发板上验证能不能安装。

这一套下来，顺利的话十五到二十分钟，不顺利的话，一个下午就没了。而且这中间每一步都是“人肉状态机”：

• 昨天构建用的编辑器版本和今天是不是同一个？
• 这次构建用的 API 版本是 10 还是 11？
• 签名用的 p12 证书文件，是不是还在上次那台机器上？
• 版本号到底写的是 0.9.1 还是 0.91？

这些都是我踩过的坑。更尴尬的是，当测试反馈某个包有问题，我去追溯“这个包是用什么参数构建出来的”，回答往往是“好像就是默认参数吧”。这种状态对于个人开发还可以忍，一旦有两个人以上在维护项目，或者需要在多个分支之间切包，立即就会乱成一锅粥。

1.2 自动化之后我实际得到的好处

把这套流程改成自动化之后，我得到的不是一个“更快的按钮”，而是一整套约束：

• 参数可固化：所有构建参数都写进脚本，团队只看代码评审，不靠口头传递。
• 版本可追溯：每次构建自动生成版本号、提交 git 记录、产物哈希，后续定位问题直接按构建号查。
• 环境可迁移：换机器时，只要照着环境准备清单配置一遍，脚本还能照常跑。
• 出包频率不受限制：以前提包是“能不提就不提”，现在每天自动出包，测试随要随有。

一句话总结：自动化的核心价值不是“快”，而是“确定性”。下文我会从链路原理、方案选型、脚本实现和踩坑排查四个维度，把这个全流程讲透。如果你正准备动手，这篇文章可以直接当参考手册用。

2. 先把链路画清楚：一个Cocos Creator工程如何变成OpenHarmony应用包

写自动化脚本之前，我花了不少时间把整条构建链路拆开看了一遍。很多人的误区是一上来就想写脚本，结果对每一步生成的产物、需要的依赖完全没概念，脚本写得再漂亮也跑不通。先理解“构建到底在干什么”，后面的所有代码才有根基。

2.1 Cocos Creator构建：资源、代码与工程模板的三步合成

Cocos Creator 在这一步做的事情，本质上是把游戏/应用资源打包，并把引擎代码和你的业务逻辑编译成目标平台需要的形态。选择 OpenHarmony 平台后，编辑器主要完成三件事：

1. 资源导入与压缩：把场景、预制体、贴图、音频等资源做格式转换和压缩，原始资源变成适合 OpenHarmony 设备加载的格式（比如纹理压缩、音频转码）。
2. 代码编译与打包：把 TypeScript/JavaScript 脚本编译成可执行代码，并连同引擎库一起打包，产物会被整合到 OpenHarmony 工程对应的资源目录里。
3. 生成 OpenHarmony 工程骨架：Cocos Creator 会根据项目配置，生成一个标准的 OpenHarmony 工程目录，里面包含 entry 模块、AppScope、构建配置、模块描述文件等。

这个过程产出的不是最终可安装的包，而是一个“可以被 hvigor 继续加工”的工程目录。你在脚本里需要关注的，就是这个目录的路径，以及它内部结构和默认配置是否符合预期。

2.2 OpenHarmony侧的hvigor构建：最终产出HAP

得到 Cocos Creator 生成的工程骨架之后，真正的 OpenHarmony 应用构建才刚开始。OpenHarmony 工程使用 hvigor 作为构建工具，它类似于 Android 生态里的 Gradle，负责做依赖解析、代码编译、资源合并、混淆等任务，最终产出 HAP 包（HarmonyOS Ability Package）。

Cocos Creator 生成的工程里其实已经带了 hvigor 相关的配置文件，比如hvigorfile.ts、oh-package.json5等。你要做的就是进入这个工程目录，执行 hvigor 的打包命令。打包命令会根据工程配置去下载依赖、编译原始代码、合并资源，最后生成一个未经签名的 HAP 包。

这一步在脚本里要注意的是工作目录切换和首次构建的依赖下载耗时。hvigor 首次跑的时候要拉取很多公共依赖，如果网络状况不佳，很容易出现超时。后文我会专门讲这个坑的排查方式。

2.3 签名与归档：决定能不能装机的最后一环

hvigor 默认产出的 HAP 包是不能直接安装到真机/开发板上的，必须经过签名。OpenHarmony 的签名机制和 Android 类似但也有差异，它需要：

• p12 证书文件：包含应用开发者的私钥，用于对包做数字签名。
• Profile 文件：描述应用包名、签名证书指纹、调试/发布类型等信息的配置文件。
• hap-sign-tool 工具：负责把 p12 证书和 profile 文件信息写入 HAP 包，完成最终签名。

签名这一步在 DevEco Studio 里通常是一键完成的，但自动化环境里必须手动调用工具链，把证书文件的路径、别名、密码、签名算法等参数逐个传进去。这块如果配置不对，最常见的表现是“包能构建但装不上”，错误信息五花八门，排查起来非常痛苦。我建议把签名参数单独抽到一个配置中心里，不要在脚本里写死。

搞清楚了这三段链路，你会发现整个自动化方案其实就是在回答三个问题：如何无人工干预地触发 Cocos Creator 构建？如何无人工干预地调用 hvigor 打包？如何无人工干预地完成签名并归档产物？接下来所有方案选型和脚本代码，都是围绕这三个问题展开的。

3. 自动化方案选型：我在Jenkins、GitLab CI和纯脚本之间怎么选

链路清楚之后，下一步是选择承载自动化的“骨架”。这里我做了一轮对比，主要候选是 Jenkins、GitLab CI 和纯本地脚本。方案没有绝对的好坏，关键看你的团队基础设施和运维成本承受能力。

3.1 三种方案的优缺点对照

我个人的判断是：如果你的项目已经托管在某个代码托管平台上并且不想额外维护服务，GitLab CI 或 GitHub Actions 更省心；如果你们喜欢“构建机 + 面板”的传统模式，Jenkins 更直接。纯脚本在我的实践里更适合做“最后一公里”的封装——比如 Jenkins 里调用的构建步骤本身就是一个 Shell 脚本，两者并不互斥。

3.2 我的最终选择与理由

我的最终选择是Jenkins Pipeline + 本地 Shell 脚本的组合。理由有三个：

1. 对构建机资源的掌控更直接：Cocos Creator 构建和 hvigor 构建都属于重型任务，我需要精确控制哪台机器执行、哪些目录有缓存、是否可以并发。这在自己的 Jenkins 节点上最可控。
2. 失败处理更灵活：Jenkins 的 Pipeline 可以细粒度地定义失败后的行为，比如重试构建、清理缓存、发送通知。纯脚本写这种逻辑虽然能实现，但复用性差。
3. 历史记录与追溯：Jenkins 天然保留每次构建的参数、日志、产物地址，配合后续的版本号规则，追溯问题非常方便。

实际落地时，Jenkins 的任务不再笨重地做“每一步鼠标点击”，而是通过 Pipeline 脚本串起来，核心逻辑全部放在 Shell 脚本里。Pipeline 只负责调度、超时控制、并发管理和结果归档。这样即使以后要迁移到其他 CI 系统，搬走的只是一套 Shell 脚本，迁移成本很低。

3.3 工程目录与产物的统一规范

不管用哪种 CI 系统，我强烈建议先约定一套工程目录规范，否则脚本很难维护。我的目录结构大致如下：

build_scripts/ build_creator.sh # 调用 Cocos Creator 命令行构建 run_hvigor.sh # 进入工程执行 hvigor 打包 sign_hap.sh # 调用 hap-sign-tool 签名 archive_hap.sh # 产物归档、重命名、生成哈希 all_in_one.sh # 总入口，按顺序调度上述脚本 workspace/ projects/ # 存放 Cocos Creator 工程源码 outputs/ # 存放构建产物 logs/ # 存放每次构建日志 cache/ # 存放构建缓存（后续优化会用到）

每次构建开始前，先清空一次 outputs 和 logs，保证“这一次构建的结果是全新的”；构建结束后，所有中间产物和最终 HAP 包全部归档在 outputs 目录下，并用构建号命名。这个规范对排查问题非常重要——你永远知道某个包是哪个构建产生的，中间产物还在不在。

4. 环境准备：90%的失败其实卡在版本和路径

很多人写自动化脚本的时候容易忽略环境准备，结果脚本写得很漂亮，但一执行就报错。从我实测的经验看，Cocos Creator 到 OpenHarmony 这条构建链路上的坑，很大比例根本不是代码逻辑问题，而是环境版本不匹配、路径找不到、证书配置不对。所以我把环境准备单独拎出来讲，这里面的细节决定了你后面省不省心。

4.1 工具链版本怎么对照最省心

我的经验是：把整个工具链的版本写死并记录下来，不要用“最新版”。原因很简单——Cocos Creator、OpenHarmony SDK、hvigor、JDK、Node.js 都有版本兼容性问题，你不知道哪个组合一定会有问题，但你知道哪个组合实测能跑通。我当前使用的组合如下：

值得留意的一点是：Cocos Creator 和 OpenHarmony SDK 各自的版本升级都可能带来接口或配置差异，升级任意一个都要做一次完整的“冒烟测试”。我试过只升级 Editor 版本、其他不动，结果构建出来的工程在 hvigor 阶段直接报错，后来发现是新版 Creator 生成的模块配置和旧版 hvigor 不兼容。

4.2 环境变量与SDK路径的配置陷阱

自动化构建最怕的是“当前用户能构建，但 Jenkins 任务构建失败”。原因往往出现在环境变量的作用域上。比如你手动开终端时，.bashrc里的JAVA_HOME被正常加载了，但 Jenkins 节点启动的 agent 进程可能没有加载这些变量。

我在实践中把所有环境变量写进一个独立的env.sh，每次构建前先 source 它：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 export PATH=$JAVA_HOME/bin:$PATH export NODE_HOME=/usr/local/node-v16.20.2-linux-x64 export PATH=$NODE_HOME/bin:$PATH export OHOS_SDK_HOME=/opt/ohos-sdk export DEVECO_SDK_HOME=/opt/DevEco-Studio/sdk export COCOS_CREATOR_PATH=/opt/CocosCreator/CocosCreator

这里最容易踩坑的是OHOS_SDK_HOME 和 DEVECO_SDK_HOME 的指向。OpenHarmony SDK 可能通过 DevEco Studio 安装，也可能通过命令行工具单独安装，不同安装方式的目录层级不一样。你用 DevEco Studio 打开一个工程时它能自动识别 SDK，但命令行环境不会自动识别，必须手动把路径告诉 hvigor。我建议在构建机器上只保留一份 SDK，并用软链统一入口，避免路径混乱。

4.3 签名文件与证书的存放方式

签名证书属于敏感文件，不要直接塞进 git 仓库。我在构建机上的做法是单独放在一个不参与版本控制的目录下，权限设为 600，并且只给构建用户可读权限。同时，证书的密码不要明文写在 Shell 脚本里，而是从 Jenkins 的凭据管理中读取，然后以环境变量的方式注入到脚本中。

举个例子，Jenkins Pipeline 里可以这样声明：

environment { SIGN_KEY_PASSWORD = credentials('sign-key-password') SIGN_PROFILE_PASSWORD = credentials('sign-profile-password') }

然后在 Shell 脚本里读取$SIGN_KEY_PASSWORD传给 hap-sign-tool。这样既避免明文密码出现在代码或日志中，也方便后续做证书轮换。签名文件的路径、别名、签名算法这些参数同样统一放在配置中，不要散落在各个脚本里。

5. 核心流水线拆解：从Creator到HAP的自动化脚本实现

环境准备好之后，剩下的就是写好构建流水线。我把这条链路抽象成四个步骤：Creator 构建、hvigor 打包、签名、归档。每一步对应一个独立脚本，最后由一个总入口脚本串起来。这样做的好处是：你可以单独调试某一个环节，也可以在任何一步失败后从缓存点继续，而不是每次从头再来。

5.1 第一步：用命令行触发Cocos Creator构建

Cocos Creator 支持命令行构建模式。命令行构建的格式大致如下：

"$COCOS_CREATOR_PATH" --project "$PROJECT_DIR" --build "platform=openharmony;debug=false;buildPath=$BUILD_PATH"

参数说明：

• --project：指向 Cocos Creator 工程目录，目录下需要有project.json或对应版本的项目配置。
• --build：构建参数，多个参数用分号分隔。platform固定为 openharmony；debug根据是否需要调试包选择；buildPath可以指定构建产出的临时目录。
• 还可以追加version、packageName等参数，让自动化脚本把版本号、包名直接注入构建流程，省去后续手动改配置的麻烦。

这一步有一个需要注意的点：Cocos Creator 命令行构建并不总是“静默”的，部分版本在首次运行时可能会尝试初始化图形环境或读取用户目录配置。我在构建机上装了一个轻量的显示环境，甚至在纯命令行的 Linux 服务器上，也会预先设置DISPLAY变量指向虚拟屏，防止构建过程因为无法初始化窗口而挂死。如果你用的是自带图形界面的机器，这个坑可以避开。

执行完成后，脚本要检查构建产物目录是否存在。这个目录一般是build/openharmony或其子目录。如果目录不存在，直接报错退出，不要继续向下走。

5.2 第二步：hvigor编译与打包

拿到 Creator 生成的 OpenHarmony 工程后，进入工程根目录，执行 hvigor 打包命令：

cd "$BUILD_PATH" # 安装依赖 ohpm install # 执行 hvigor 构建 ./hvigorw assembleHap --mode module -p product=default

ohpm install会按照oh-package.json5拉取项目依赖；hvigorw是 hvigor 的 wrapper 工具，类似 Gradle wrapper，会保证使用指定版本的 hvigor 执行构建。assembleHap是拼接 HAP 的 task，--mode module表示按模块构建，-p product=default指定产品类型。

这一步我先说几个常见问题的预防：

• 首次执行ohpm install时依赖下载量大，一定要给 CI 任务设置足够的超时时间，至少在十分钟以上，否则很容易被默认超时杀掉。
• hvigor 构建输出里会出现警告信息，但不要只看最后几行是绿的就觉得成功了，一定要检查最终 HAP 文件是否生成、文件大小是否合理。
• 如果工程里有多个模块，而你需要出整包，可能要增加-p module=entry@default这样的参数。具体以你的工程模块结构为准，可以在本地先手动跑通一遍再写进脚本。

构建成功后，hvigor 会在模块的build/default/outputs/下生成 HAP 文件。在脚本里把这个路径记录下来，下一步签名要用。

5.3 第三步：自动签名与版本号注入

签名这步的脚本思路是把必要的参数全部从外部传入，避免在代码里硬编码。hap-sign-tool 调用方式大致如下：

java -jar "$HAP_SIGN_TOOL" sign-app \ -keyAlias "$SIGN_KEY_ALIAS" \ -signAlg "SHA256withECDSA" \ -mode "localSign" \ -appCertFile "$CERT_FILE" \ -profileFile "$PROFILE_FILE" \ -inFile "$UNSIGNED_HAP" \ -outFile "$SIGNED_HAP"

参数说明：

• keyAlias：证书别名，创建 p12 时设置的。
• signAlg：OpenHarmony 签名常用的算法是SHA256withECDSA。
• appCertFile：你的 p12 证书文件路径。
• profileFile：应用的 profile 文件，由构建证书/profile 生成。
• inFile和outFile：输入的未签名 HAP 和输出的已签名 HAP。

版本号注入这件事，我习惯放在签名之前做。具体做法是：在 Creator 命令行构建时通过version参数传入版本号，或者在 hvigor 构建前修改工程里的app.json5/module.json5中的版本字段。比较稳妥的方式是在 Creator 构建那一层就指定好版本号，因为这样整个 HAP 版本管理都贯穿一致。版本号我建议用三位段式（如 1.2.0），或者带构建号（如 1.2.0.45），方便快速定位是哪个构建产生的包。

5.4 第四步：产物归档与通知

签名完成之后，把最终的 HAP 包复制到集中的一个产物目录，并做两件小事：

1. 生成校验哈希：用sha256sum计算 HAP 的哈希值，存放到同目录的.sha256文件中。后续任何人拿到包都可以校验完整性。
2. 记录构建元信息：把 Git 提交号、构建参数、Cocos Creator 版本、hvigor 版本、构建时间等写入一个build_info.txt文件。

这两步对出问题后的追踪特别有用。我遇到过测试反馈“这个包有问题”，结果根据 build_info 发现包是在某次旧环境配置下构建的，跟代码本身没关系。没有这些元信息，排查过程会非常痛苦。

归档完成后，Jenkins Pipeline 里可以继续执行通知步骤，比如发送到企业内部通讯工具或邮件。通知内容里带上产物下载地址、版本号、构建号，让需要的人可以直接拿包去测。

6. 实测中的高频失败与完整排查链路

脚本写完只是开始，真正磨人的是踩坑。我把自己遇到的频率最高的三个问题完整写下排查思路，照着这个顺序去查，大多数失败都能定位。

6.1 场景一：构建命令长时间不返回，任务“挂死”

现象：Jenkins 任务卡在 Cocos Creator 构建或 hvigor 构建阶段，持续十几分钟没有任何输出，最后要么超时被杀，要么一直挂着。

排查链路：

1. 先看构建机上的进程，确认命令是死了还是还在运行。如果是 Java/Cocos 子进程还活着，说明只是没有输出回显。
2. 检查是在哪个阶段挂的。Cocos Creator 阶段挂死，多半和图形环境初始化有关，比如缺少 X 相关组件、内存不足。hvigor 阶段挂死，多半是依赖下载卡住或内存不足。
3. 看日志文件。Cocos Creator 日志可以重定向到文件里，hvigor 日志默认在工程目录的hvigor子目录下有细致输出。
4. 针对“无输出回显”问题，我的解决办法是为每个构建命令加--max-log-length或者直接重定向到日志文件，并且用timeout命令包一层，超过阈值就强杀并回传日志。

timeout 1800 "$COCOS_CREATOR_PATH" --project ... > "$LOG_DIR/creator_build.log" 2>&1

这样即使挂死，也有日志可查，不会干瞪眼。

6.2 场景二：hvigor依赖下载失败导致构建中断

现象：ohpm install或 hvigor 执行时，网络下载依赖失败，报 SSL 证书错误、超时或者仓库地址无法访问。

排查链路：

1. 确认构建机是否能正常访问依赖仓库。企业的内网构建机经常有网络限制，导致仓库地址不可达。
2. 检查 hvigor 配置中的仓库地址。如果默认仓库访问不稳定，可以考虑切换到内网镜像仓库，或者把公共依赖提前缓存好。
3. 查看具体依赖版本。有些依赖下载重定向失败，是因为版本号使用了动态版本（如^1.0.0），每次解析结果都不一样，本地缓存也没有命中。全部改成锁定版本可以降低随机失败概率。
4. 最实用的兜底方案：在构建机上维护一个本地缓存目录，首次成功构建后把依赖目录整体压缩备份，后续构建直接从缓存恢复。配合 hvigor 自身的缓存机制，可以显著降低对网络的依赖。

6.3 场景三：签名的包装不上，安装时报“签名不一致”

现象：HAP 构建成功、签名也成功返回 0，但安装到 OpenHarmony 设备上时直接失败，提示签名错误或证书不匹配。

排查链路：

1. 确认签名用的 p12 证书和 profile 文件是否配套。OpenHarmony 签名是“证书 + profile”双重绑定，两者必须对应同一个应用和同一个开发者。很多人从网上找了一个证书，又拿另一个项目的 profile，必然失败。
2. 检查签名算法是否被目标设备支持。老设备的系统版本如果较旧，可能不支持某些新算法。
3. 检查 HAP 包内各模块的签名是否一致。如果你的工程有多个 HAP（比如 entry 和另一个 feature 模块），OpenHarmony 安装时会校验所有 HAP 的签名一致性——必须用同一套证书签所有模块，不能用两套证书。
4. 用官方工具或日志查看具体错误码。设备端安装失败的原因可以从hilog或者 DevEco Studio 的设备日志中看到，密码错误、证书过期、profile 应用名不匹配，这些错误码各不相同。逐条对照比盲目换证书有效得多。

6.4 我的通用排查顺序

踩了足够多的坑之后，我总结了一套通用排查顺序，遇到任何构建问题都按这个顺序走：

1. 看日志：任何一步构建都有日志，先找到对应的日志文件，看最后一个报错点。
2. 确认版本组合：Cocos Creator、SDK、hvigor、JDK、Node 的组合是否与之前成功构建时一致。
3. 确认环境变量：相关的 SDK 路径、JAVA_HOME、PATH 是否在当前构建进程中正确加载。
4. 确认权限：构建用户是否对依赖目录、缓存目录、产物目录有读写权限。
5. 复现最小化：把构建参数简化到最小，手动在构建机上执行一次，排除 CI 层面的干扰，同时方便观察完整日志。

这套顺序帮我解决了很多看起来“玄学”的失败。多数情况下，问题都出在环境变量或版本组合上，而不是代码本身。

7. 让流水线“跑得稳”：缓存、并发与通知的几个优化

当流水线能稳定跑通，下一步就是让它跑得快、跑得省。我在这里分享几个我认为回报率最高的优化点。

7.1 缓存体系：把重复劳动降到最低

构建过程中最耗时的两个部分，一是 Cocos Creator 对工程资源的重编译，二是 hvigor 对依赖的重解析。这两部分其实都有缓存机制，关键在于怎么让你的自动化流程尽可能命中缓存。

hvigor 的缓存目录通常在用户目录下的.hvigor或项目build/.hvigor下。我的做法是把这个缓存目录映射到构建机的固定位置，并且每次构建前不清理它，只在版本升级时手动清理一次。这就让“同一依赖的不同构建”能共享缓存，第二次构建能比第一次快三分之一。

Cocos Creator 构建侧的缓存逻辑相对复杂，直接清理临时目录反而容易踩坑。我建议让构建临时目录按构建号隔离，例如outputs/tmp_$BUILD_NUMBER，这样一方面避免并发冲突，另一方面如果你想复现某一历史构建的完整现场，目录还在，可以直接进去看。

7.2 并行构建与构建机资源分配

如果团队的构建任务比较频繁，可以让 Jenkins 节点同时跑多个任务。但有一个前提：要精确控制并发数。Cocos Creator 构建和 hvigor 构建都是内存大户，单台构建机同时跑两个构建，内存很容易被吃满，反而导致互相拖慢。

我实际的做法是单节点最多允许一个“重型构建”任务并发，同时允许轻量任务（如打包配置校验、静态检查）并行。Jenkins 里通过节点的执行器数量控制这个并发度，可以有效避免资源争抢造成的偶发失败。

7.3 失败通知与日志收集

自动化构建最怕的就是失败之后没人知道。我在 Pipeline 全局加了一个post阶段，无论成功还是失败，都会把本次构建的日志压缩上传到固定的存储目录，并且把日志链接、产物地址、失败原因摘要发给相关人员。

我特意强调“失败原因摘要”而不是“原始日志”。因为完整日志动辄上百兆，直接发给人看很容易被忽略。我的做法是脚本在失败时自动抓取最后 50 行日志里的关键错误行（比如ERROR、FAILED开头的行），汇总成一个简短的摘要。这样接收人一眼就知道大概是什么问题，需要详细日志再点链接查看。

7.4 版本号的自动生成规则

版本号看似小事，实际很影响管理效率。我用的规则是：主干版本号 + 构建号。比如代码版本是 1.2.0，Jenkins 构建号是 45，最终 HAP 的版本号就是1.2.0.45，同时把这个版本号写进 HAP 文件名里。

这样做的最大好处是：任何人拿到包，从文件名就能知道它是哪个主版本产物、第几次构建。脚本里只需要一行读取 Jenkins BUILD_NUMBER 然后拼进去：

APP_VERSION="${MAJOR}.${MINOR}.${PATCH}.${BUILD_NUMBER}"

相比手动维护版本号，这个做法不仅省事，还能彻底避免“忘记改版本号导致覆盖旧包”这种低级失误。

最后再分享一个小技巧：整条流水线里，我最常被问到的问题并不是脚本怎么写，而是“如何在 Cocos Creator 构建失败时快速知道是资源问题还是代码问题”。我的做法是在构建日志里提前埋好关键字，比如资源构建阶段开始和结束时各打印一行，这样抓取摘要时能快速区分阶段归属。这个小细节看起来不起眼，实际排查问题时能帮你少折腾半小时。