TL;DRhvigor 构建失败日志动辄几十层堆栈但真实工程的失败原因高度集中在八类。本文给出开源工具 hmharness 的 harmony_build_doctor 八类签名分类表每类附具体修复命令可直接对号入座排查。适用于 HarmonyOS/OpenHarmony 应用开发者与 CI 维护者。先说工具全貌hmharness 是一个开源的 HarmonyOS/OpenHarmony 开发智能体框架MITgithub.com/swsgbl/hmharness把工程创建、检查、构建、签名、安装、启动、日志读取和结果验证接成本地工具链让 AI 不只是生成代码还要用本机环境证明结果。它不是 DevEco Studio 的替代品而是开发智能体和鸿蒙工具链之间的验证层。本文只展开其中一环构建失败诊断 harmony_build_doctor。一、为什么 hvigor 报错难读hvigor 失败时输出完整堆栈墙真正的原因往往只有一行。人工排查靠经验扫描AI 编程智能体更容易被日志尾部误导。系统化解法是签名分类用正则匹配日志末 8000 字符中的稳定失败签名regex-on-tail、有序匹配 first-hit-wins毫秒级返回分类和修复动作离线可用可单测。二、八类失败签名与修复方法1. sdk-homeSDK 路径问题报错特征Invalid value of DEVECO_SDK_HOME / not find sdk。修复设置 HM_DEVECO_HOME默认 C:\DevEco-Studio或导出 DEVECO_SDK_HOME/sdk 后重试。2. sdk-versionSDK 版本不匹配报错特征错误码 Specification Limit ViolationcompatibleSdkVersion 与已安装 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-sourceArkTS 源码错误报错特征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.ts3 个单元测试守护。口径npm hmharness/cli 0.20.3GitHub Release 页为 v0.18.12安装以 npm 为准。项目与华为、开放原子无隶属关系。GitHubhttps://github.com/swsgbl/hmharness证据页https://swsgbl.github.io/hmharness/evidence/
HarmonyOS hvigor 构建失败排查指南：八类常见报错与修复方法
TL;DRhvigor 构建失败日志动辄几十层堆栈但真实工程的失败原因高度集中在八类。本文给出开源工具 hmharness 的 harmony_build_doctor 八类签名分类表每类附具体修复命令可直接对号入座排查。适用于 HarmonyOS/OpenHarmony 应用开发者与 CI 维护者。先说工具全貌hmharness 是一个开源的 HarmonyOS/OpenHarmony 开发智能体框架MITgithub.com/swsgbl/hmharness把工程创建、检查、构建、签名、安装、启动、日志读取和结果验证接成本地工具链让 AI 不只是生成代码还要用本机环境证明结果。它不是 DevEco Studio 的替代品而是开发智能体和鸿蒙工具链之间的验证层。本文只展开其中一环构建失败诊断 harmony_build_doctor。一、为什么 hvigor 报错难读hvigor 失败时输出完整堆栈墙真正的原因往往只有一行。人工排查靠经验扫描AI 编程智能体更容易被日志尾部误导。系统化解法是签名分类用正则匹配日志末 8000 字符中的稳定失败签名regex-on-tail、有序匹配 first-hit-wins毫秒级返回分类和修复动作离线可用可单测。二、八类失败签名与修复方法1. sdk-homeSDK 路径问题报错特征Invalid value of DEVECO_SDK_HOME / not find sdk。修复设置 HM_DEVECO_HOME默认 C:\DevEco-Studio或导出 DEVECO_SDK_HOME/sdk 后重试。2. sdk-versionSDK 版本不匹配报错特征错误码 Specification Limit ViolationcompatibleSdkVersion 与已安装 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-sourceArkTS 源码错误报错特征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.ts3 个单元测试守护。口径npm hmharness/cli 0.20.3GitHub Release 页为 v0.18.12安装以 npm 为准。项目与华为、开放原子无隶属关系。GitHubhttps://github.com/swsgbl/hmharness证据页https://swsgbl.github.io/hmharness/evidence/
