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_HOMEC:\Program Files\Huawei\DevEco Studio\jbr $env:NODE_HOMED:\dev\command-line-tools\tool\node $env:DEVECO_SDK_HOMED:\dev\command-line-tools\sdk $env:OHOS_BASE_SDK_HOMED:\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 默认指向旧 JDKHarmonyOS 的签名材料解析可能直接失败。设置完以后可以先确认版本where java java -version where node如果where java的第一项不是 DevEco JBR就不要急着继续构建。为什么要管 hvigor daemonhvigor 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 继承环境问题。处理顺序应该是检查where java和java -version。切到 DevEco JBR。停掉旧 hvigor daemon。用--no-daemon --stacktrace重跑。再判断是不是证书或 Profile 不匹配。这样可以避免把签名环境问题误改成业务代码问题。不要为了验证随手改build-profile.json5build-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。推荐顺序是先跑assembleHap --no-daemon --stacktrace拿到完整失败阶段。如果像环境问题检查 Java/Node/SDK 路径。停 hvigor daemon 后重跑。如果是资源、缓存或 AGC 正式包输出再考虑clean assembleApp。clean会拉长反馈时间也可能掩盖“到底是哪一步开始失败”的信息。只有当你已经确认需要重新生成正式包或者缓存明显污染时再使用它更稳。推荐的本地构建脚本片段如果团队经常在命令行构建 HarmonyOS 项目可以把环境设置和构建命令整理成固定片段$env:JAVA_HOMEC:\Program Files\Huawei\DevEco Studio\jbr $env:NODE_HOMED:\dev\command-line-tools\tool\node $env:DEVECO_SDK_HOMED:\dev\command-line-tools\sdk $env:OHOS_BASE_SDK_HOMED:\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。这种写法适合工程复盘。例如passedassembleHap --no-daemon --stacktrace not runassembleApp本次未生成 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 包能上传 AGCrelease 包能构建也不代表已绑定到版本绑定成功也不代表已提交审核。D:\dev\command-line-tools\bin\hvigorw.bat --mode module -p moduleentrydefault 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、构建输出目录。