火星后继者第一次用 DevEco Studio 创建 HarmonyOS NEXT 工程时，真正拦住我的不是 ArkTS 语法，也不是 Stage 模型，而是最前面的工程同步环节直接报了依赖安装错误。弹窗提示写得很概括：ohpm install failed，Sync 失败。那会儿我连工程目录里每个文件是干什么的都说不全，更别提“ohpm 是把依赖装到哪里”这种问题了。后来一边查目录结构一边排查日志，才意识到鸿蒙 NEXT 项目的依赖安装机制和以往 Android、前端工程都不一样，很多“看着像网络问题”的报错，根子其实埋在工具链衔接上。这篇文章我会把 HarmonyOS NEXT 纯血工程目录从根目录到 entry 模块完整拆出来讲，再把一次“最初的依赖安装报错”从头到尾的排查过程记录下来，给你一条可以直接照着走的路线。
如果你是刚建好第一个 NEXT 工程、看到 Sync 红色提示就头皮发麻的开发者，这篇内容应该能帮你省下不少瞎折腾的时间。
1. 第一次 Sync 就报错：先搞清楚这是哪一类失败
1.1 报错现场：IDE 的红字只是冰山一角
创建工程后 IDE 会自动执行依赖同步。很多人的第一反应是“我还没写代码，为什么同步就挂了”。我也一样，那天新建了一个 API 12 的 Empty Ability 工程，工程模板刚展开，右下角就开始转圈，几秒后 Build 窗口出现类似这样的输出：
code复制Start sync ...
hvigor version: 5.0.6
ohpm install ...
ERROR: Failed to run ohpm install.
Sync failed, please try again.
日志里没有指明是哪个依赖下载失败，也没说是网络还是文件权限，就一句干巴巴的 Failed to run ohpm install。如果你这时直接回 IDE 点 Sync Now 重试，大概率还是同样结果，来回几趟以后就容易产生“是不是鸿蒙开发环境没装好”的自我怀疑。
但我想先给你一个关键认知：Sync 阶段报的“依赖安装失败”，并不等于某一个第三方包真的坏了。依赖安装是一个长链路，它要完成初始化工程配置、检查构建工具版本、识别依赖清单、连接依赖仓库、下载依赖包、写入本地模块目录这几件事。任何一环出了问题，最后都会以“安装失败”的形式体现在日志最外层。
所以第一步不是去删工程重建，而是分辨当前是哪种失败。我把这类报错分成三类：工程配置类、环境工具链类、依赖仓库访问类。它们的表现特征差异很大，后面我会用一整节讲怎么区分。
1.2 读报错的三个坐标：阶段、关键字、执行命令
依赖报错不是拿来看的，是用来定位的。我给自己定了一套排查坐标，后来遇到任何 Sync 失败都先按这个走。
第一个坐标是阶段。观察日志里 ohpm install 前面是否还有别的信息。它能告诉我们：工程模式有没有解析成功、hvigor 插件有没有加载出来、依赖清单有没有被读取。如果日志连 hvigor 版本都打印不出来，那问题基本在构建工具层，而不是依赖仓库层。
第二个坐标是关键字。日志里出现 Cannot find module、ENOTFOUND、ECONNREFUSED、Exit code 1、Version mismatch 这些词，对应的问题方向差别非常大。比如 Cannot find module 通常和 Node 执行环境、工具链路径有关，而 ENOTFOUND 才更接近仓库访问不了的问题。很多人一看到 failed 就跑去调网络，结果定位错了方向。
第三个坐标是手动命令。IDE 里的 Sync 按钮有它自己的封装，日志往