《2026鸿蒙NEXT纯血开发与AI辅助》第四章 对鸿蒙next项目结构目录详解以及实战解决一个最初的依赖安装的报错·卓伊凡

在 鸿蒙NEXT（HarmonyOS NEXT） 项目中，项目结构目录是至关重要的，它决定了代码和资源的组织方式，也影响到后续开发的效率和模块化。这里我将以 DevEco Studio 6.0.2(22) 为例，详细解读 鸿蒙NEXT 项目的标准目录结构，帮助你更好地理解每个文件和文件夹的作用。

一、鸿蒙NEXT项目结构概述

在鸿蒙NEXT项目中，项目结构采用了三层架构模型（AppScope、Module、entry），同时支持 ArkUI 和 ArkTS 开发。鸿蒙NEXT的项目结构被分为多个层次，每个层次有不同的功能和配置，以下是鸿蒙NEXT项目结构的基础布局：

• AppScope：应用全局配置目录，所有跨模块或跨设备共享的资源存放在此。
• Module：模块级目录，包含应用功能模块的代码和资源。
• entry：入口模块，通常对应应用的主界面或主逻辑部分。

二、项目目录结构详解

1. AppScope 目录

AppScope 是项目的全局配置目录，主要存放应用级别的资源和配置信息。一般来说，DevEco Studio 会自动为你生成 AppScope 目录，并且这个目录中的内容不可更改。AppScope 目录下通常包含以下文件：

• app.json5：应用的全局配置文件，包含应用的基本信息、版本信息、设备类型的配置等。此文件是项目级配置文件，用来向编译工具、操作系统、以及应用市场提供应用的基本信息。示例：

{
  "appName": "MyApp",
  "appVersion": "1.0.0",
  "platform": "HarmonyOS",
  "targetSdkVersion": "5.0.0(10)"
}

• resources：应用级别的资源文件，存放例如全局图标、共享的图片、字体文件等资源。多个模块共享这些资源时会直接引用它们。

2. Module 目录

每个模块都是一个独立的单元，包含了特定功能的代码和资源。Module 目录可以包含多个模块，例如 entry、library 等。在 DevEco Studio 中，模块的名字可以由开发者自己定义，但通常会包含一些标准模块名，例如：

• entry：这个模块通常是应用的入口模块，包含应用的主界面和主逻辑，通常也是第一个被加载的模块。
• library：如果有多个模块共享的公共功能代码，可以将这些代码放到 library 模块中，其他模块需要使用时引用它。

Module 目录下包含以下文件和文件夹：

• src/main/ets：这是模块中存放 ArkTS 页面和业务代码的地方。通常，每个页面（比如主页面、设置页面等）都会有一个对应的 *.ets 文件。示例：

import { createPage } from '@ohos/arkui';
export default createPage({
  onInit() {
    console.log('Page Initialized');
  }
});

• src/main/resources：存放模块特定的资源文件，通常包括该模块的图标、图片、音视频等资源。
• module.json5：模块的配置文件，包含了该模块的基本信息、模块依赖、模块配置等。示例：

{
  "moduleName": "EntryModule",
  "dependencies": ["LibraryModule"]
}

• hvigorfile.ts：这个文件是模块级的构建脚本，用于定义该模块的编译任务和构建流程。

3. entry 目录

entry 是最常见的模块之一，表示应用的入口点。它通常是你应用的主页面或主逻辑，包含应用启动时需要加载的资源和组件。

entry 目录通常会包含以下文件：

• src/main/ets：包含页面的 ArkTS 代码。
• src/main/resources：入口模块使用的资源文件。
• module.json5：配置入口模块的相关信息。

示例：

{
  "moduleName": "MainEntry",
  "dependencies": []
}

三、关键配置文件详解

1. app.json5

app.json5 是项目的主配置文件，它包含应用的全局配置信息。这个文件在应用的启动和构建过程中会被读取，决定了应用的行为和与系统的兼容性。

主要配置项包括：

• appName：应用名称。
• appVersion：应用版本。
• platform：目标平台，通常为 HarmonyOS。
• targetSdkVersion：目标 SDK 版本。

2. module.json5

module.json5 是每个模块的配置文件，包含了该模块的依赖、功能、资源等配置。通过该文件，DevEco Studio 可以管理和协调不同模块之间的关系。

3. build-profile.json5

build-profile.json5 是构建配置文件，定义了项目的编译配置、目标产品、产品配置等。它是构建流程的核心文件，影响到项目最终的构建和打包输出。

4. oh-package.json5

oh-package.json5 是用来管理依赖和模块包的配置文件。它帮助开发者自动化安装和配置所需的模块和资源。

四、构建和调试流程

1. 构建（Build）

DevEco Studio 中的构建流程通常由 Hvigor 来完成，所有模块的构建任务和依赖管理都通过 hvigor 进行协调。DevEco Studio 提供了 Build 面板来显示构建过程中的日志和结果，开发者可以在这里看到构建是否成功，哪些依赖未能安装等信息。

2. 调试（Debug）

在 DevEco Studio 中，调试可以通过 Run > Edit Configurations 来进行设置。DevEco Studio 支持多种调试类型，包括 Dual (ArkTS/JS + Native)、Native 等。通过选择不同的调试模式，开发者可以调试不同的代码模块。

五、常见问题

1. 工程依赖问题：DevEco Studio 会在 File > Sync and Refresh Project 时自动安装项目的所有依赖。如果遇到依赖未安装或者版本冲突的问题，可以手动点击这个按钮来同步依赖。
2. 构建错误：常见的构建错误通常是由于配置文件缺失或者模块之间依赖未正确声明。开发者可以通过 Build > Build App 来查看构建输出的日志，定位错误的具体位置。

我们一开始打开软件就发现有错误报错

"F:\deveco\DevEco Studio\tools\node\node.exe" "F:\deveco\DevEco Studio\tools\hvigor\bin\hvigorw.js" --sync -p product=default --analyze=normal --parallel --incremental --no-daemon

Installing dependencies...

> hvigor ERROR: 00308020 Operation Error

Error Message: C:\Users\Administrator\.hvigor\wrapper\tools\node_modules\.bin\pnpm.cmd install execute failed. More details:

 ERR_PNPM_NO_MATCHING_VERSION  No matching version found for @ohos/hvigor-ohos-arkui-x-plugin@4.22.4 while fetching it from https://repo.harmonyos.com/npm/

This error happened while installing a direct dependency of C:\Users\Administrator\.hvigor\project_caches\de6b9e52fed71677f6b1e6cecec31703\workspace

The latest release of @ohos/hvigor-ohos-arkui-x-plugin is "4.22.3". Published at 2026/1/28

If you need the full list of all 41 published versions run "$ pnpm view @ohos/hvigor-ohos-arkui-x-plugin versions"

* Try the following:

> Check whether the version of the failed package exists in the npm repository.

> More info: https://developer.huawei.com/consumer/cn/doc/architecture-guides/common-v1_26-ts_494-0000002547627959

Process finished with exit code -1

然后这个问题是根据您提供的错误日志分析，问题核心是依赖包版本不匹配导致的构建失败。以下是详细解决方案：

错误原因分析

ERR_PNPM_NO_MATCHING_VERSION 
No matching version found for @ohos/hvigor-ohos-arkui-x-plugin@4.22.4

1. 版本不存在：npm仓库中不存在指定的4.22.4版本（最新版为4.22.3）
2. 依赖冲突：项目配置或缓存强制锁定了不存在的版本
3. 网络问题：可能未正确访问HarmonyOS官方仓库

解决方案
第一步：修改依赖版本

1. 打开项目根目录的package.json文件
2. 找到@ohos/hvigor-ohos-arkui-x-plugin依赖项
3. 将版本号从4.22.4改为4.22.3（或移除版本号使用最新版）

第二步：清理缓存

# 删除项目缓存
rm -rf C:\Users\Administrator\.hvigor\project_caches\*
# 删除node_modules
rm -rf node_modules
# 清除pnpm缓存
pnpm store prune

第三步：重建依赖

# 重新安装依赖
pnpm install
# 同步项目
hvigorw --sync -p product=default

预防措施

1. 版本检查：执行以下命令确认可用版本：

pnpm view @ohos/hvigor-ohos-arkui-x-plugin versions

1. 代理设置：

• • 进入DevEco Studio设置 > Appearance & Behavior > System Settings > HTTP Proxy
  • 选择No proxy或手动配置可用代理

1. 仓库验证：

curl https://repo.harmonyos.com/npm/@ohos/hvigor-ohos-arkui-x-plugin

正常应返回版本列表

关键提示：若持续失败，请检查项目配置中是否硬编码了无效版本号（如build-profile.json5或hvigorfile.ts），建议改用版本范围声明如~4.22.0避免锁定特定版本。

然后这个问题本章节并未解决，因为 一直约束有要求 是 hvigor-ohos-arkui-x-plugin 4.22.4版本

但是 目前所能使用版本pnpm view @ohos/hvigor-ohos-arkui-x-plugin versions
[
'2.1.2', '2.1.7', '2.3.1', '3.0.0',
'3.1.1', '4.2.1', '4.2.2', '4.2.3',
'4.2.4', '4.2.7', '4.2.8', '4.2.10',
'4.2.11', '4.2.12', '4.2.14', '4.2.15',
'4.2.24', '4.2.25', '4.2.27', '4.17.5',
'4.17.6', '4.18.0', '4.19.0', '4.19.2',
'4.19.6', '4.19.7', '4.19.8', '4.20.0',
'4.20.3', '4.20.4', '4.20.5', '4.21.0',
'4.21.1', '4.21.2', '4.21.3', '4.22.2',
'4.22.3'
PS F:\zhuoyifantest> pnpm install @ohos/hvigor-ohos-arkui-x-plugin@4.22.3
Packages: +1
+
Progress: resolved 1, reused 0, downloaded 1, added 1, done

而 安装了 pnpm install @ohos/hvigor-ohos-arkui-x-plugin@4.22.3 版本也不可用，所以直接陷入僵局，本视频弄得我有点烦躁！但是下个视频会更新，问题肯定会解决。

我把此问题也反馈在鸿蒙开发者群里了。这一集是非常抓狂的一集，因为尝试了很多方法，但是版本问题存在一些问题，总之环境还没通，之前的老版本是很早就通了的。