命令行走通 hvigor 构建：三个报错怎么排【鸿蒙心迹】

DevEco Studio 里点构建没有问题，一换到 PowerShell 就失败，是这个项目早期最影响验证效率的问题之一。

命令行构建并不是为了显得专业。它解决的是一个很实际的需求：改完代码以后，开发脚本或 AI 助手能不能自己跑一次编译，而不是每次都等人回到 IDE 点按钮。

我们遇到的三个主要问题分别是 SDK 路径、SDK 组件和签名材料。排查顺序也应该按这个顺序来。

第一关：DEVECO_SDK_HOME 无效

第一次在终端运行 hvigor 时，任务记录里留下的是：

DEVECO_SDK_HOME invalid

IDE 能找到 SDK，不代表新开的 PowerShell 也知道 SDK 在哪里。先从 DevEco Studio 的 SDK 设置页确认真实目录，再在当前终端设置环境变量：

$env:DEVECO_SDK_HOME = '<OpenHarmony SDK 目录>'

然后使用与当前 DevEco Studio 配套的 hvigor，而不是随手调用 PATH 里另一个版本：

& '<DevEco Studio 安装目录>\tools\hvigor\bin\hvigorw.bat' assembleHap --mode module

这里有两个容易忽略的点。

第一，$env:DEVECO_SDK_HOME 默认只对当前 PowerShell 会话生效。新开终端后需要重新设置，或者把路径放进专用构建脚本。

第二，SDK 路径和 DevEco Studio 安装路径不是一回事。前者指向 SDK，后者用于找到配套的 hvigor。把两者混在一起，日志会继续提示找不到组件。

第二关：00303168 SDK component missing

路径正确以后，我们又遇到过：

hvigor ERROR: 00303168 Configuration Error
Error Message: SDK component missing.
Please verify the integrity of your SDK.

这时继续改环境变量通常没有用。错误已经说明 hvigor 找到了 SDK，只是工程需要的组件没有完整安装。

处理方法是回到 DevEco Studio 的 SDK 管理页，对照工程使用的 API/SDK 版本检查组件状态。升级 IDE、换电脑或者手动清理过 SDK 目录后，都可能出现版本目录还在、其中组件却不完整的情况。

这个错误还有一个判断方法：如果构建在 ArkTS 编译任务开始前就停止，就不能把它写成“代码编译失败”。准确说法应当是“SDK 环境检查阶段被阻断”。

这个区分很重要。我们曾经有几次改动完成了源码静态检查，但因为本机缺少 SDK 组件，只能记录构建未执行，不能写成已经通过。

第三关：signing/material 不存在

SDK 和 ArkTS 编译都通过以后，打包阶段可能继续报：

ENOENT: no such file or directory, stat '<工程目录>\signing\material'
BUILD FAILED

这类错误不是业务代码问题，而是签名配置引用了本机不存在的材料。

签名文件通常不会完整提交到仓库。换电脑、重新拉取工程或清理工作区以后，都需要重新生成或关联调试签名。正式发布时还要换成与应用和 Profile 对应的正式材料。

排查时先看 build-profile.json5 里的签名配置指向哪里，再确认本机对应目录和文件是否存在。不要为了让构建通过，把私钥或敏感签名材料直接提交到 Git。

我的固定排查顺序

顺序	检查项	能确认什么
1	DEVECO_SDK_HOME	终端是否找到正确 SDK
2	SDK 管理页组件状态	工程所需组件是否完整
3	hvigor 与 DevEco 版本	是否调用了配套工具
4	签名配置和本机材料	HAP 是否具备打包条件
5	实际构建任务输出	ArkTS 编译和 HAP 打包是否通过

当命令返回 BUILD SUCCESSFUL，只能说明本次指定的构建任务通过。它不等于微信授权、支付回调或原生渲染已经在真机通过。这些功能仍然要单独记录真机条件和结果。

在这个项目中，后续多个阶段确实通过 assembleHap --mode module 或对应打包任务完成了 ArkTS 编译与 HAP 打包；也有个别阶段因为本机 SDK 组件缺失，只完成静态检查。把两种结果分开写，才能让下一次排查知道究竟从哪里继续。

命令行构建真正带来的价值，是把“我觉得改好了”变成一条可重复执行的验证命令。

你现在的 HarmonyOS 工程能脱离 IDE 构建吗？如果不能，先看失败发生在 SDK 检查、ArkTS 编译，还是签名打包阶段。

---

系列上一篇：《ArkTS 不是 TypeScript：我踩过的 6 条编译红线【鸿蒙心迹】》

系列下一篇：《上架前先对齐应用名、包名和版本号【鸿蒙心迹】》