DevEco 构建环境排障：JBR、Node、SDK 与 hvigor daemon 的正确组合

DevEco 构建环境排障：JBR、Node、SDK 与 hvigor daemon 的正确组合

HarmonyOS ArkTS 工程的构建问题，经常不是某一行页面代码导致的。Project028桌面卡片工坊在开发过程中遇到过几类典型问题：ArkTS 编译通过，但SignHap阶段失败；切了JAVA_HOME之后错误还在；本地装包时拿到了过期产物；release Profile 权益正确，但证书私钥不匹配。

这篇记录一套更稳的排障方法：先固定 DevEco JBR、Node 和 SDK，再用--no-daemon规避旧 hvigor daemon 继承错误环境，最后把编译错误、签名错误和 AGC 包错误分开看。

先固定构建环境

Project028 使用 DevEco 命令行工具构建时，会先显式设置几个环境变量：

$env:JAVA_HOME='C:\Program Files\Huawei\DevEco Studio\jbr' $env:NODE_HOME='D:\dev\command-line-tools\tool\node' $env:DEVECO_SDK_HOME='D:\dev\command-line-tools\sdk' $env:OHOS_BASE_SDK_HOME='D:\dev\command-line-tools\sdk\default\openharmony' $env:PATH="$env:JAVA_HOME\bin;$env:NODE_HOME;$env:DEVECO_SDK_HOME\default\openharmony\toolchains;D:\dev\command-line-tools\bin;$env:PATH"

这一步的目的不是“美化命令”，而是避免系统默认 Java 或 Node 抢先进入 PATH。尤其是 Windows 上，如果 shell 默认指向旧 JDK，HarmonyOS 的签名材料解析可能直接失败。

设置完以后，可以先确认版本：

where java java -version where node

如果where java的第一项不是 DevEco JBR，就不要急着继续构建。

为什么要管 hvigor daemon

hvigor daemon 会复用之前的构建进程。如果上一次 daemon 是在旧 JDK 或旧 PATH 下启动的，即使当前 shell 已经切了JAVA_HOME，错误也可能继续出现。

所以遇到环境类问题时，建议先停 daemon，再用--no-daemon跑：

& 'D:\dev\command-line-tools\bin\hvigorw.bat' --stop-daemon-all & 'D:\dev\command-line-tools\bin\hvigorw.bat' assembleHap --no-daemon --stacktrace

如果命令行工具版本不支持--stop-daemon-all，至少要保证后续构建使用--no-daemon。这样当前 shell 的JAVA_HOME、NODE_HOME和 SDK 路径才更可控。

assembleHap和assembleApp不要混用判断

Project028 的常用验证分两类：

& 'D:\dev\command-line-tools\bin\hvigorw.bat' assembleHap --no-daemon --stacktrace & 'D:\dev\command-line-tools\bin\hvigorw.bat' clean assembleApp --no-daemon --stacktrace

它们的用途不同：

• assembleHap：适合本地编译、安装、页面交互和真机验证。
• assembleApp：适合生成 AGC 可上传的.app包。

如果只是修页面 UI、输入框、桌面 Form 本地表现，优先看assembleHap和设备验证。如果要重新提交 AGC，才需要clean assembleApp，并且上传后还要在 AGC 版本页重新绑定最新包。

不要因为本地assembleApp通过，就直接说 AGC 审核问题已修复。AGC 审核看到的是当前版本绑定的包，不是你本地磁盘上刚生成的包。

区分 ArkTS 编译错误和签名错误

构建失败时，先看失败阶段。

如果失败在CompileArkTS，通常是代码问题，例如：

• ForEachitem 或 key 函数没有显式类型。
• @Builder里写了顶层局部const。
• Row.alignItems()误传了FlexAlign。
• Stack子组件使用了不允许的Blank。

如果失败在SignHap，就不一定是业务代码。Project028 曾遇到过类似错误：

11014003 Init keystore failed parseAlgParameters failed: ObjectIdentifier()

这类更像是 JDK、签名材料或 daemon 继承环境问题。处理顺序应该是：

1. 检查where java和java -version。
2. 切到 DevEco JBR。
3. 停掉旧 hvigor daemon。
4. 用--no-daemon --stacktrace重跑。
5. 再判断是不是证书或 Profile 不匹配。

这样可以避免把签名环境问题误改成业务代码问题。

不要为了验证随手改build-profile.json5

build-profile.json5里通常包含证书路径、Profile 路径、keyAlias 和密码相关字段。排查时可以确认路径和证书指纹是否匹配，但不要把密码字段写入文章、日志或聊天回复。

对 Project028 来说，后期 release 包还遇到过一种情况：Profile 已经包含代理提醒权益，但绑定的发布证书不是本机持有私钥的那一张，SignHap仍然失败：

ERROR: 11111002 Certificates error

这种问题靠改 ArkTS 页面无效，应该回到 AGC Profile 和本地 release 私钥链路上核对：

• 当前 Profile 是否是新生成的。
• Profile 是否包含目标开放能力。
• Profile 绑定的证书指纹是否和本地.p12私钥匹配。
• debug 验证和 release 提交是否用了各自正确的 Profile。

最重要的是：不要在文章或记录里暴露keyPassword、storePassword或任何私钥材料。

clean不是第一反应

很多构建问题可以通过环境重置解决，不一定一上来就clean。推荐顺序是：

1. 先跑assembleHap --no-daemon --stacktrace，拿到完整失败阶段。
2. 如果像环境问题，检查 Java/Node/SDK 路径。
3. 停 hvigor daemon 后重跑。
4. 如果是资源、缓存或 AGC 正式包输出，再考虑clean assembleApp。

clean会拉长反馈时间，也可能掩盖“到底是哪一步开始失败”的信息。只有当你已经确认需要重新生成正式包，或者缓存明显污染时，再使用它更稳。

推荐的本地构建脚本片段

如果团队经常在命令行构建 HarmonyOS 项目，可以把环境设置和构建命令整理成固定片段：

$env:JAVA_HOME='C:\Program Files\Huawei\DevEco Studio\jbr' $env:NODE_HOME='D:\dev\command-line-tools\tool\node' $env:DEVECO_SDK_HOME='D:\dev\command-line-tools\sdk' $env:OHOS_BASE_SDK_HOME='D:\dev\command-line-tools\sdk\default\openharmony' $env:PATH="$env:JAVA_HOME\bin;$env:NODE_HOME;$env:DEVECO_SDK_HOME\default\openharmony\toolchains;D:\dev\command-line-tools\bin;$env:PATH" where java java -version & 'D:\dev\command-line-tools\bin\hvigorw.bat' assembleHap --no-daemon --stacktrace

要生成 AGC 包时，再单独执行：

& 'D:\dev\command-line-tools\bin\hvigorw.bat' clean assembleApp --no-daemon --stacktrace

这两个命令最好不要在报告里混成一句“构建通过”。应分别写清楚：

• assembleHap是否通过。
• assembleApp是否通过。
• 是否安装到设备。
• 是否完成页面或系统能力验证。

验证报告应该怎么写

Project028 的.agent记录里，会把验证结果分成passed、failed、not run。这种写法适合工程复盘。

例如：

passed：assembleHap --no-daemon --stacktrace not run：assembleApp，本次未生成 AGC 正式包 not run：真机截图，本次只修构建环境

这样可以明确知道：哪些证据已经拿到，哪些没有跑，哪些结论不能下。

小结

DevEco 构建排障的关键，不是记住某一个错误码，而是分层判断：

• CompileArkTS失败，多半回到代码和 ArkTS 严格模式。
• SignHap失败，优先看 JBR、daemon、证书和 Profile。
• assembleApp通过，只说明本地正式包生成了，不代表 AGC 正在审核这个包。
• 真机验证要再接上hdc连接、tmp 探针、安装、启动和截图。

对 HarmonyOS 项目来说，构建链路本身就是工程的一部分。环境可重复、验证可追溯，后面的 UI、桌面卡片、代理提醒和 AGC 审核修复才不会被基础环境问题反复打断。

hvigor 环境问题要先定界，再修复

构建环境章节要补充“定界”而不是只列命令。Project028 后续发布遇到过 Profile、证书、版本号、AGC 绑定等问题，如果一上来就改源码，容易把平台问题误判成代码问题。hvigorw assembleHap、assembleApp、hap-sign-tool verify-*应该形成固定证据链。

开发调试通常使用 HAP，正式上架使用.app。这两者的签名 Profile、证书链、构建输出、验证方式都不同。关键边界是：debug 包通过并不代表 release 包能上传 AGC；release 包能构建也不代表已绑定到版本；绑定成功也不代表已提交审核。

D:\dev\command-line-tools\bin\hvigorw.bat --mode module -p module=entry@default assembleHap --no-daemon D:\dev\command-line-tools\bin\hvigorw.bat clean assembleApp --no-daemon --stacktrace java -jar hap-sign-tool.jar verify-app -inFile build\outputs\default\Project028-default-signed.app

敏感信息处理也要纳入边界。签名文件路径、Profile 名称可以记录，密码字段不能写入文章。Project028 的.agent会话可以记录“复用本机已有加密配置”，但 CSDN 面向公开发布，必须避免粘贴build-profile.json5中的密码值。

落地检查清单

• 是否区分 HAP 调试包和 APP 上架包。
• 是否说明构建成功、签名验证、AGC 绑定是三件事。
• 是否提醒不要公开签名密码和私钥路径细节。
• 是否覆盖11111002 Certificates error的排查方向：Profile 绑定证书与本地私钥是否匹配。
• 是否覆盖真实路径：build-profile.json5、AppScope/app.json5、构建输出目录。