鸿蒙Harmony实战开发教学(No.2)-鸿蒙新项目创建+目录配置！（新手入门指南）
对于刚接触鸿蒙开发的新手而言，首次打开 DevEco Studio 项目时，往往会因陌生的目录结构感到困惑。本文将系统拆解鸿蒙项目的核心目录、配置文件及关键规则，帮助开发者快速掌握各模块作用，为后续开发奠定基础。
目录
一、工程级核心目录解析（2 个核心目录，需重点掌握）
1.1 AppScope：应用全局配置与资源目录（不可修改目录名）
1.2 Module：业务开发核心目录（以默认entry模块为例）
二、3 个核心配置文件（决定应用构建与依赖管理）
1.build-profile.json5：项目构建配置文件，核心作用包括：
2.hvigorfile.ts：编译脚本文件，基于 Hvigor 构建工具编写，主要作用包括：
3.oh-package.json5 + oh_modules：三方依赖管理相关文件：
三、编译与发布的 2 个关键规则
1.编译阶段规则：
2.发布阶段规则：
四、新手必避的 2 个核心问题
五、下期内容预告
一、工程级核心目录解析（2 个核心目录，需重点掌握）
鸿蒙项目工程级目录主要包含AppScope与Module两类，二者分工明确，共同支撑应用基础架构。
1.1 AppScope：应用全局配置与资源目录（不可修改目录名）
AppScope是应用级的全局配置与资源根目录，目录名称不允许修改，否则会导致项目编译失败。其下核心文件 / 目录功能如下：
app.json5：应用核心配置文件（可理解为应用 “身份标识与全局配置中心”），主要配置内容包括：
- 应用唯一标识（Bundle Name，如com.example.harmonyapp）；
- 应用基础信息（应用名称、图标、版本号、最小兼容 API 版本等）；
- 全局权限声明（若应用需申请系统级权限，可在此统一配置）；
- resources：应用级资源库，存储全局共享的资源文件（如应用图标、全局样式、公共字符串等）。当该目录下的资源与Module目录下的资源同名时，应用级资源会覆盖模块级资源，适用于统一管理多模块应用的全局资源。
1.2 Module：业务开发核心目录（以默认entry模块为例）
Module是应用的业务模块目录，开发者的核心代码（如页面、逻辑处理）均在此编写。鸿蒙项目默认生成entry模块（入口模块，即应用启动后首先加载的模块），其核心子目录功能如下：
- src/main/ets：ArkTS 源码目录，存储应用的业务逻辑代码，核心子目录 / 文件包括：
- EntryAbility：应用入口能力类，负责管理应用的生命周期（如启动、前台切换、销毁），是系统识别应用入口的关键；
- pages：页面目录，存储应用的所有页面文件（以.ets为后缀），如首页、详情页等，页面间的路由跳转需基于此目录结构配置。
- src/main/resources：模块级资源目录，存储当前模块专属的资源文件，不可随意删除，否则可能导致页面样式、资源引用失效。核心子目录包括：
- base/element：存储基础元素配置文件（以 JSON 格式为主），如字符串（string.json）、颜色（color.json）、尺寸（dimens.json）、样式（style.json）等，支持多语言、多分辨率适配；
- base/media：存储媒体资源文件，如图片（.png、.jpg）、音频（.mp3）、视频（.mp4）等，资源引用时需通过指定路径调用；
- rawfile：存储原始资源文件（如配置文件、第三方库资源等），该目录下的资源不会被系统编译处理，需通过绝对路径引用。
- module.json5：模块配置文件，定义当前模块的核心信息，包括:(1) 模块类型（如entry入口模块、feature功能模块）；(2) 设备适配范围（如支持手机、平板、智慧屏等哪些设备形态）；(3) 模块依赖关系（如依赖的其他feature模块）；(4) 能力声明（如当前模块具备的服务能力、后台任务等）。
二、3 个核心配置文件（决定应用构建与依赖管理）
以下 3 个配置文件直接影响应用的编译打包、依赖管理，是开发与发布环节的关键：
1.build-profile.json5：项目构建配置文件，核心作用包括：
- 管理构建参数（如编译输出路径、代码混淆规则）；
- 配置应用签名信息（发布应用到华为应用市场时必须配置，确保应用安全性与唯一性）；
- 定义产品变体（如开发环境、测试环境、生产环境的差异化配置）。
2.hvigorfile.ts：编译脚本文件，基于 Hvigor 构建工具编写，主要作用包括：
- 执行默认编译流程（如源码编译、资源打包、HAP 生成）；
- 支持自定义构建任务（如编译前自动复制资源文件、编译后自动执行测试脚本等）。
3.oh-package.json5 + oh_modules：三方依赖管理相关文件：
- oh-package.json5：声明项目依赖的三方库（如鸿蒙官方组件库、第三方 UI 库），需指定依赖包名称、版本号；
- oh_modules：依赖包存储目录，执行ohpm install命令后，会自动从鸿蒙包管理中心（OHPM）下载依赖包并存储于此，目录由工具自动生成，无需手动修改。
三、编译与发布的 2 个关键规则
理解鸿蒙项目的编译与发布规则，可避免因配置错误导致的编译失败或上架问题：
1.编译阶段规则：
- 源码编译：ArkTS 源码（.ets文件）会被编译为字节码文件（.abc），再由鸿蒙系统虚拟机解析执行；
- 资源合并：AppScope/resources与Module/resources的资源会进行合并，同名资源按 “应用级覆盖模块级” 的规则处理；
- 配置合并：app.json5中的全局配置（如 Bundle Name、版本号）会合并到module.json5中，确保模块配置与应用全局配置一致。
2.发布阶段规则：
- 应用唯一标识（Bundle Name）必须全局唯一：app.json5中配置的 Bundle Name 是应用在华为应用市场的唯一标识，不可与其他已上架应用重复，否则会导致上架审核失败。
四、新手必避的 2 个核心问题
- 禁止修改AppScope目录名：AppScope是鸿蒙工程的固定全局目录，其路径与名称由 DevEco Studio 默认约定，修改后会导致编译工具无法识别全局配置与资源，直接触发编译失败。
- 资源冲突处理：当AppScope/resources与Module/resources存在同名资源时，编译后会优先使用AppScope下的资源。若需使用模块级资源，需修改资源名称或通过绝对路径指定引用。
五、下期内容预告
下一篇将聚焦 “鸿蒙首个页面开发实战”，全程实操讲解，帮助新手快速完成第一个鸿蒙页面开发。
建议收藏本文，后续开发中可随时对照目录结构排查问题。若有疑问，可在评论区留言，将逐一解答。