TL;DR

hvigor 构建失败日志动辄几十层堆栈，但真实工程的失败原因高度集中在八类。本文给出开源工具 hmharness 的 harmony_build_doctor 八类签名分类表，每类附具体修复命令，可直接对号入座排查。适用于 HarmonyOS/OpenHarmony 应用开发者与 CI 维护者。

先说工具全貌：hmharness 是一个开源的 HarmonyOS/OpenHarmony 开发智能体框架（MIT，github.com/swsgbl/hmharness），把工程创建、检查、构建、签名、安装、启动、日志读取和结果验证接成本地工具链，让 AI 不只是生成代码，还要用本机环境证明结果。它不是 DevEco Studio 的替代品，而是开发智能体和鸿蒙工具链之间的验证层。本文只展开其中一环：构建失败诊断 harmony_build_doctor。

一、为什么 hvigor 报错难读

hvigor 失败时输出完整堆栈墙，真正的原因往往只有一行。人工排查靠经验扫描，AI 编程智能体更容易被日志尾部误导。系统化解法是签名分类：用正则匹配日志末 8000 字符中的稳定失败签名（regex-on-tail、有序匹配 first-hit-wins），毫秒级返回分类和修复动作，离线可用可单测。

二、八类失败签名与修复方法

1. sdk-home：SDK 路径问题

报错特征：Invalid value of DEVECO_SDK_HOME / not find sdk。修复：设置 HM_DEVECO_HOME（默认 C:\DevEco-Studio）或导出 DEVECO_SDK_HOME=/sdk 后重试。

2. sdk-version：SDK 版本不匹配

报错特征：错误码 Specification Limit Violation，compatibleSdkVersion 与已安装 SDK 不符。修复：用 hmh devices/check 查已装 SDK 版本，修 build-profile.json5 的 products[0].compatibleSdkVersion。注意：schema 校验不检查版本合理性，这类问题由诊断器兜底。

3. signing：签名配置失效

报错特征：signingConfigs / keystore / .p12 相关。调试场景九成是自动签名过期：DevEco 里重新开启自动签名（File > Project Structure > Signing），或清空 signingConfigs 走无签名校验。正式发布需要 AppGallery 真实证书。

4. ohpm-deps：依赖解析失败

报错特征：ohpm install ERROR / ERESOLVE / ohos_modules。修复：项目根目录执行 ohpm install --all，并核对 oh-package.json5 中版本在仓库真实存在。

5. hvigor-env：构建环境损坏

报错特征：hvigor daemon / node: not found / Cannot find module hvigor。修复：设置 HM_DEVECO_HOME 让内置 node 可达；删除项目 .hvigor 缓存目录后重试——daemon 缓存腐坏是最常见原因。

6. arkts-source：ArkTS 源码错误

报错特征：ERROR: ArkTS / arkts-数字编号 / Struct must。这是唯一需要改代码的类别：读日志中第一个 ERROR 块的 file:line:pos，修复缺 import、类型错误、struct 语法问题。

7. config：工程配置错误

报错特征：build-profile / module.json5 / parse json。修复：先跑 harmony_schema_check——毫秒级点名 module.json5/build-profile.json5 的坏字段，不用等 3 分钟堆栈。

8. network：网络失败

报错特征：ECONN / timeout / registry / fetch failed。修复：检查代理配置；ohpm 换官方镜像源（ohpm config set registry https://ohpm.openharmony.cn/ohpm/）。

三、两条设计原则

一、未知签名永不隐藏：分类不到的失败原样透传日志尾部和第一个 ERROR 块；反复出现的模式才应进入签名表。二、签名表自身可进化：第 8 类 sdk-version 是 hmharness 自进化机制（SELFFEED）在实战中补充的——判据锚定错误码而非提示文案，避免工具版本更新导致分类失效。

四、使用方法

智能体调用：把 harmony_build 失败输出传给 harmony_build_doctor 的 log 参数，返回 kind + 证据行 + fix；或传 project 路径自动构建再诊断。人工使用：npm i -g @hmharness/cli。

参考与口径

分类表源码：packages/domain-harmony/src/builddoctor.ts（3 个单元测试守护）。口径：npm @hmharness/cli 0.20.3；GitHub Release 页为 v0.18.12，安装以 npm 为准。项目与华为、开放原子无隶属关系。

GitHub：https://github.com/swsgbl/hmharness

证据页：https://swsgbl.github.io/hmharness/evidence/