火星后继者第一次用 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 按钮有它自己的封装，日志往往被吞掉一半。更直接的办法是在工程根目录打开终端，手动执行一次 ohpm install，让错误信息完整暴露出来。后面实战那节我就是靠这一步找到根因的。
记住一句话：报错日志是给你破案的线索，不是只用来确认“失败了”的结论。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. HarmonyOS NEXT 项目目录拆解：哪些文件决定了 Sync 的行为
2.1 根目录：AppScope、hvigor 配置与工程级构建文件
先看整个工程的顶层结构。我拿 DevEco Studio 默认生成的 NEXT 工程举例，删掉 IDE 自动生成的缓存后，真正需要关心的目录大概是这么几块：
code复制ProjectRoot/
├── AppScope/
│ ├── app.json5
│ └── resources/
├── entry/
├── hvigor/
│ └── hvigor-config.json5
├── oh_modules/
├── build-profile.json5
├── hvigorfile.ts
├── oh-package.json5
├── local.properties
└── .gitignore
AppScope 是应用级配置的“壳”，它不是模块，而是整个应用的门面。app.json5 里放的是 bundleName、版本号、应用图标这些一个应用最顶层的属性。真正写业务代码时你可能很少改动这里，但它决定了安装到设备后系统看到的“你是谁”。
build-profile.json5 是工程级的构建配置，和 Android 里根目录的 build.gradle 角色有点像。它定义了产品、签名配置、编译 SDK 版本、兼容 SDK 版本，以及这个工程包含哪些模块。模块靠 modules 字段声明，并且用 srcPath 指向模块目录。这个字段一旦和实际目录对不上，Sync 阶段就会报模块找不到或者目标不匹配的错误。
hvigor/hvigor-config.json5 是我觉得很多人会忽略、但排错时很关键的文件。它声明了当前工程要使用的 hvigor 版本，以及 hvigor 需要加载的插件。IDE 在 Sync 时先读这个配置，再去本地查找匹配版本的 hvigor。如果你从别处拷贝工程、或者 DevEco Studio 升级过但工程还留着旧配置，这一步很容易出现版本对不上的问题。
根目录还有一个 hvigorfile.ts，它负责向 hvigor 暴露工程级构建任务。默认模板里内容很简洁，通常不需要手改，但只要它被误删、被错误格式化，构建系统也会直接罢工。
2.2 entry 模块内部：真正写代码的地方长什么样
工程级配置只是门槛，真正常打交道的是 entry 模块。它是一个典型的 HAP 模块，目录结构通常长这样：
code复制entry/
├── src/
│ ├── main/
│ │ ├── ets/
│ │ │ ├── entryability/
│ │ │ │ └── EntryAbility.ets
│ │ │ └── pages/
│ │ │ └── Index.ets
│ │ ├── resources/
│ │ └── module.json5
│ └── ohosTest/
├── build-profile.json5
├── hvigorfile.ts
├── oh-package.json5
└── obfuscation-rules.txt
你可能注意到，它和工程根目录有“同名文件”，比如 build-profile.json5、hvigorfile.ts、oh-package.json5。这是鸿蒙多模块工程的一个特点：每一层都有自己独立的构建配置和依赖清单。模块级配置会覆盖或补充工程级配置，比如 entry/build-profile.json5 中会指定这个模块是 HAP，还可以分别配置 debug 和 release 的混淆规则。
src/main/ets 是 ArkTS 源码所在目录。entryability 里放的是应用入口 Ability，可以理解成一个应用的启动入口类；pages 目录里放页面级 UI 代码，比如模板默认生成的 Index.ets 就是首页。刚开始学习时，你改得最多的就是 pages 下的文件。
src/main/module.json5 是模块级配置文件。它描述这个模块有哪些 Ability、申请了什么权限、页面的路由入口长什么样。如果你新增一个页面或 Ability，需要对应更新这个文件。
resources 目录则是资源文件的集中地。默认会拆成 base、en_US、zh_CN 等目录，base 表示默认资源，其它目录是不同语言和地区的覆盖资源。字符串、颜色、图片、媒体资源、配置文件都按类别放在各自的子目录里。如果资源文件名重复、或者资源引用在代码里写错，也会出现编译报错，但它不属于依赖安装问题，这里不展开。
src/ohosTest 是测试代码目录，默认模板会引入 @ohos/hypium 测试框架依赖。这也是很多人第一次 Sync 时下载量比较集中的地方，如果断在 hypium 下载上，别太意外。
2.3 两个容易让人误会的目录：oh_modules 与 .hvigor
oh_modules 长在工程根目录，里面放着 ohpm 安装的依赖包。它的角色很像前端工程里的 node_modules。新手容易犯的错是看到这个目录很大、结构很深，就不敢动它。实际上它是完全自动生成的，放心删除也不会丢代码，重新执行依赖安装就会再生成。
同样容易被误会的还有 .hvigor 目录。它保存的是 hvigor 在本地生成的工程缓存，包括插件的状态、任务执行记录等。有些项目从压缩包里解压出来、或者从 Git 仓库克隆下来后 Sync 异常，把 .hvigor 和 oh_modules 一起删掉再重新同步，往往就好了。
local.properties 也是本地生成文件，一般不会提交到 Git。它记着 SDK 路径、Node 路径等本机环境信息。如果你换了电脑、或者把工程目录移动了位置，这里的路径可能失效，导致 IDE 找不到 SDK 或 Node，后续任何和构建、依赖安装相关的操作都会失败。下次看到 Sync 阶段报“找不到 SDK”这类错误，可以先检查它。
3. hvigor 和 ohpm 是怎样合作安装依赖的
3.1 看似一步“Sync”，背后其实走了三段路
我排错之前，一直以为 IDE 里点一下 Sync，就是把配置同步到工程里那么轻。实际上它做了三件互相独立的事：解析工程和模块配置、加载 hvigor 构建环境、执行 ohpm 安装依赖。
第一步解析的是工程级 build-profile.json5、各 module.json5 和编译 SDK 版本，目的是知道这个工程包含哪些模块、每个模块用什么 SDK 去编译。第二步是检查 hvigor 版本、加载 hvigor 插件，hvigor 是鸿蒙 NEXT 的构建引擎，所有编译任务都由它编排。第三步才是安装依赖，hvigor 找到模块内的 oh-package.json5，再调用 ohpm 工具去下载和链接依赖。
这三段路只要有一段出问题，IDE 都会把错误归纳到 Sync。但每一段对应的日志关键字完全不同。如果你看到报错信息里混杂着 module.json5 解析异常，那就要回看模块配置，而不是去折腾 ohpm 源地址。我建议你把“Sync”理解成一个总入口，真正要盯的是 Sync 过程中暴露出的阶段性日志。
3.2 为什么 Node 环境一乱，依赖安装就跟着报错
鸿蒙 NEXT 的构建工具链底层依赖 Node.js 运行时。hvigor 是一套跑在 Node 上的构建框架，ohpm 也是一个基于 Node 的命令行工具。DevEco Studio 安装时会一并带上一套内置 Node，并把它和 SDK 工具链绑定好。多数情况下开发者不需要主动安装 Node，直接在 IDE 里操作就可以。
但问题往往出在“本机已经装过别的 Node”这种情况。开发者的电脑上很可能已经有 nvm、nodejs 官方包、或者某些工具自动装了一个 Node。当你在终端里执行 ohpm 或 hvigorw 命令时，系统会按照 PATH 环境变量找命令。如果它优先找到了全局 Node 环境下的旧版 ohpm、或者一个版本很老的新版 node，依赖安装就可能在执行中途以各种诡异方式失败。
这就是我常说的“工具链串台”。在 IDE 里点 Sync 可能使用内置 Node 没问题，但在外部终端手动执行命令时却用了全局 Node。有时候反过来，IDE 配置被污染后 Sync 失败，外部终端却一切正常。遇到这类问题，先反思一个问题：你安装 ohpm 或 hvigor 时，到底是给哪个 Node 环境装的？这个问题的答案往往就是破案关键。
3.3 oh-package.json5 里的依赖版本，不是随手写的
oh-package.json5 是 ohpm 的依赖清单。模块级和工程级各有一份。它的结构和前端 package.json 很像，用 dependencies 字段声明运行依赖，用 devDependencies 声明开发期依赖，比如测试框架 @ohos/hypium 就属于开发期依赖。
版本号可以写精确版本，比如 1.0.21，也可以写语义化版本范围，比如 ^1.0.21、~1.0.21。我建议在自己负责的工程里尽量锁定精确版本。原因是鸿蒙生态还处于快速迭代期，第三方库的接口变化比较频繁，一旦用范围匹配，某次 Sync 时拉到了新版本，可能出现运行时 API 不兼容，而代码和错误提示里并不会直接告诉你“版本换了”。
在继续讲实战之前，我还想提醒一个细节：源码目录下通常没有 package-lock.json 这类强锁定文件，ohpm 的依赖解析结果放在 oh_modules 目录中。所以你换电脑、别人拉你代码后，跑起来依赖版本可能不完全一致。项目组里最好约定统一使用固定版本号，配合 oh-package-lock.json5 这类锁文件一起提交，才能保证大家构建结果一致。
4. 实战排查：代码能补全但 ohpm install 一直失败
4.1 用“最笨”的方式从头复现，日志反而清晰了
前面铺垫了这么多结构知识，现在进入这次“最初的依赖安装报错”的正题。我当时的情况是这样：新建的 API 12 工程，IDE 可以正常识别项目结构，ArkTS 代码也能有语法提示，说明工程解析阶段已经过了。但 Sync 就是挂在 ohpm install 上，反复提示 Failed to run ohpm install。
更奇妙的是，那个工程里我只用了模板自带的依赖，没有额外引入任何三方库。这说明问题几乎不可能是依赖包本身的 bug，而更有可能出在 ohpm 命令的执行环境上。
我在工程根目录打开终端，手动执行了 ohpm install，想看完整错误。结果没等下载开始，直接给了一行 Node 风格的报错：
code复制node:internal/modules/cjs/loader:1092
Cannot find module 'C:\Users\xxx\AppData\Roaming\npm\node_modules\@ohos\ohpm\bin\ohpm.js'
看到 node_modules\@ohos\ohpm 这个路径我就反应过来了。这个工程正在调用的 ohpm，根本不是 DevEco Studio SDK 内置的 ohpm，而是我之前某次为了命令行方便，用全局 npm 安装的 @ohos/ohpm 包。这个全局包在 Node 升级或者清理后，依赖已经不完整，模块文件找不到了。
这就是一个典型的“环境串台”问题。IDE 的 Sync 原本应该使用自带的工具链，但工程里某些配置或环境变量让命令行解析到了全局 npm 路径下的同名命令。于是每次 Sync 都会在调试工具上栽倒，而 IDE 本身的代码解析、语法提示这些不依赖 ohpm 的功能却一切正常，所以我产生了“工程没问题但安装不行”的矛盾感。
4.2 根因确认：全局 Node 环境与 SDK 自带工具链冲突
为了确认根因，我做了三步验证。
第一步是执行 where ohpm（Windows 上）或 which ohpm（macOS/Linux 上），查看命令行实际找到的 ohpm 路径。结果显示指向的是全局 npm 目录下的 @ohos\ohpm，而不是 DevEco Studio 的 SDK 工具链目录。
第二步是查看当前 Node 版本，再对比 DevEco Studio 要求的 Node 版本范围。全局 Node 版本明显偏旧，而 hvigor 5.x 对 Node 有最低版本要求。版本不够，带着依赖去初始化 hvigor 插件时自然跑不起来。这就是为何同一台机器打开别的项目有时也会出现类似报错，因为全局环境乱了，谁用谁倒霉。
第三步，也是在 IDE 里执行的验证：打开 DevEco Studio 自带终端，执行 ohpm -v，发现内置终端里用的 ohpm 路径和外部终端不同，而且版本号正常。这说明 DevEco 自带的工具链是完好的，只是外部终端、或者说 IDE Sync 过程中可能加载到的环境变量路径，把命令指向了错误位置。
到这里，根因可以确定了：不是依赖仓库连不上，也不是三方包有坑，而是我本机全局 Node 环境里残留了一个不完整的 @ohos/ohpm，它抢占了 SDK 自带 ohpm 的位置，导致依赖安装阶段根本无法正常启动工具。
4.3 最终处理：让工程重新走回官方工具链
知道了根因，解决起来就不复杂了。我没有去重新安装那个全局 ohpm，因为即使装上，它的版本也未必和当前 DevEco Studio 的 hvigor 完全匹配。最稳妥的办法是把工具链的执行路径拉回官方默认。
以下是当时每一步的处理记录。
第一，在外部终端里卸载或移走冲突的全局包。
我用 npm 卸载了全局的 @ohos/ohpm。如果你不确定机器上有哪些全局包，可以先执行 npm ls -g --depth=0 查看，再决定卸载哪一个。这个全局包本身不必要，因为 DevEco Studio 自带的 ohpm 功能更完整、版本也跟随 IDE 自动管理。
第二，确认 DevEco Studio 内置 ohpm 的路径。
在 DevEco Studio 的 SDK 目录下通常能找到 `toolchains/oh