《鸿蒙原生应用从0-1构建：项目工程结构与核心配置全景解析》

前言

在移动端开发的宏大历史中，每一次操作系统的底层重构，都伴随着工程架构的全面进化。随着 HarmonyOS NEXT（纯血鸿蒙）的正式发布，华为彻底抛弃了对传统安卓 AOSP 代码的兼容，转向了完全自主可控的底层内核与 ArkUI 声明式框架。

对于无数想要在 2026 年抢占鸿蒙生态红利的开发者而言，“从 0 到 1 构建鸿蒙原生应用”的第一步，绝不是盲目地去写 UI 页面，而是必须深刻理解鸿蒙项目底层的工程结构、编译构建管线（Build Pipeline）、包管理哲学（OHPM）以及极其严苛的安全静态检查规范。

本文将以一个真实的 HarmonyOS 项目核心配置文件源码为切入点，为您进行像素级、架构级别的深度拆解。无论您是从 Android/iOS 转型而来的移动端老兵，还是从前端跨界而来的新锐开发者，这篇文章都将帮您彻底打通 HarmonyOS 工程化架构的任督二脉。

📑 目录

1. 鸿蒙工程的宏观宇宙：Stage 模型与目录拓扑
2. **构建大脑深度解剖：build-profile.json5**
3. 安全即生命：code-linter.json5与密码学防线
4. **包管理的新纪元：OHPM 与oh-package.json5**
5. **构建流调度与本地环境：hvigorfile.ts&local.properties**
6. 架构师总结：从零开始的最佳实践

一、 鸿蒙工程的宏观宇宙：Stage 模型与目录拓扑

在 HarmonyOS 中，应用模型经历了从 FA（Feature Ability）模型到Stage 模型的历史性跨越。Stage 模型是目前鸿蒙原生开发的绝对主流，它将应用的进程管理、UI 生命周期与后台任务进行了极其优雅的解耦。

在 DevEco Studio 中创建一个全新的 Empty Ability 工程后，您面对的不再是单一的代码堆砌，而是一个高度模块化的目录树。

1.1 核心目录结构速览

为了后续配置文件的讲解，我们需要先理清各个层级的文件坐标：

• AppScope/：应用全局配置区。这里存放了应用的全局图标、名称定义以及全局的app.json5。

• entry/：应用的主模块（HAP包）。一个应用可以有多个模块（Feature/HSP/HAR），但必须有一个且仅有一个 Entry 模块。

• src/main/ets/：ArkTS 代码的核心战场。

• entryability/：存放EntryAbility.ets，这是应用在内存中的进程入口与生命周期控制器。

• pages/：存放具体的 UI 页面（如Index.ets）。

• src/main/resources/：模块级资源目录（图片、多语言字符串）。

• module.json5：该模块的声明文件，定义了所需的系统权限（Permissions）和导出的 Ability。

• 根目录构建配置文件：即我们今天要深度剖析的build-profile.json5、oh-package.json5、hvigorfile.ts等。

二、 构建大脑深度解剖：build-profile.json5

如果说代码是应用的血肉，那么构建配置就是应用的骨骼。build-profile.json5是鸿蒙工程特有的构建配置文件，它掌控着从源代码到最终 HAP/APP 产物的生死大权。

我们来看这段极其标准的工程级源码：

{ "app": { "signingConfigs": [], "products": [ { "name": "default", "signingConfig": "default", "targetSdkVersion": "6.0.2(22)", "compatibleSdkVersion": "6.0.2(22)", "runtimeOS": "HarmonyOS", "buildOption": { "strictMode": { "caseSensitiveCheck": true, "useNormalizedOHMUrl": true } } } ], "buildModeSet": [ { "name": "debug", }, { "name": "release" } ] }, "modules": [ { "name": "entry", "srcPath": "./entry", "targets": [ { "name": "default", "applyToProducts": [ "default" ] } ] } ] }

2.1 顶级节点与多产品矩阵 (products)

在app节点下，最重要的莫过于products数组。现代的商业应用开发，往往需要一套代码打包出不同的形态（比如：普通用户版、企业定制版、或者不同的渠道包）。鸿蒙通过products完美支持了这一需求。

• **targetSdkVersion与compatibleSdkVersion**：
  这里的值被设定为"6.0.2(22)"。这说明工程基于极高版本的 HarmonyOS SDK 构建。

• targetSdkVersion决定了编译器在编译时使用的 API 集合。

• compatibleSdkVersion则是向下兼容的底线，决定了该应用能安装在多老的鸿蒙系统上。保持两者一致，意味着应用采取了“激进且纯粹”的最新框架路线。

• runtimeOS: "HarmonyOS"：
  这是一个极其标志性的参数。它宣告了此应用运行的底层环境是纯血的HarmonyOS，彻底切断了与 OpenHarmony（开源鸿蒙）的含糊地带。

2.2 严格模式 (strictMode)：架构师的纪律鞭尺

"buildOption": { "strictMode": { "caseSensitiveCheck": true, "useNormalizedOHMUrl": true } }

为什么高级工程必须开启strictMode？

1. caseSensitiveCheck: true（大小写敏感校验）：在 Windows 和 macOS 上，文件系统默认是大小写不敏感的。如果你在代码里import Utils from './utils'，但文件名其实是Utils.ets，在本地编译能通过，但一旦推送到 Linux 架构的 CI/CD 云端流水线，瞬间就会引发找不到文件的“血案”。开启此项，DevEco Studio 会在编译第一秒就拦截这种低级错误。
2. useNormalizedOHMUrl: true（标准化模块路径）：在复杂的跨 Module 引用中，开启此项能强制使用标准的ohos/module寻址协议，极大提升了编译器解析依赖树的速度，避免循环引用陷阱。

2.3 模块挂载拓扑 (modules)

"modules": [ { "name": "entry", "srcPath": "./entry", "targets": [ { "name": "default", "applyToProducts": [ "default" ] } ] } ]

这里定义了当前工程的物理模块。applyToProducts: ["default"]是一个非常精妙的设计。
如果你的工程里有一个VIP_Feature模块，你可以设置它只applyToProducts: ["vip_product"]。这样在打普通版安装包时，该模块的代码将被彻底从最终的 APP 产物中剔除，实现了物理级别的动态组件下发。

表 1：build-profile.json5 核心参数速查

三、 安全即生命：code-linter.json5与密码学防线

在万物互联的时代，鸿蒙系统将安全隐私提升到了战略高度。在工程化层面，这体现为极其严苛的静态代码检查规范（Linter）。

我们来看看这段令人望而生畏的安全规则配置：

{ "files": [ "**/*.ets" ], "ignore": [ "**/src/ohosTest/**/*", "**/node_modules/**/*", "**/build/**/*" ], "ruleSet": [ "plugin:@performance/recommended", "plugin:@typescript-eslint/recommended" ], "rules": { "@security/no-unsafe-aes": "error", "@security/no-unsafe-hash": "error", "@security/no-unsafe-mac": "warn", "@security/no-unsafe-dh": "error", "@security/no-unsafe-dsa": "error", "@security/no-unsafe-ecdsa": "error", "@security/no-unsafe-rsa-encrypt": "error", "@security/no-unsafe-rsa-sign": "error", "@security/no-unsafe-rsa-key": "error", "@security/no-unsafe-3des": "error" } }

3.1 性能与语法的双基座 (ruleSet)

在检查代码时，鸿蒙不仅使用了标准的 TS 检查（@typescript-eslint/recommended），还强制引入了@performance/recommended。这意味着如果你在ForEach循环里忘记写keyGenerator函数，或者滥用了会引起内存泄漏的闭包，编译器直接会报黄警告。鸿蒙拒绝垃圾代码。

3.2 密码学的高压红线 (@security/*)

这是这份配置中最硬核的精华！鸿蒙对所有涉嫌“弱密码学”的调用都设置了"error"（编译阻断级别的错误）：

1. 对称加密红线（no-unsafe-aes,no-unsafe-3des）：
   绝对禁止使用3DES，因为它早已被数学界证明可以被暴力破解。
   同时，如果在使用AES算法时选择了不安全的ECB模式，也会报 error。开发者必须老老实实去使用带有初始化向量（IV）的AES-GCM或AES-CBC模式。
2. 非对称加密红线（no-unsafe-rsa-encrypt等）：
   禁止使用不带有安全填充机制（如 OAEP 或 PKCS1）的 RSA 裸算法。
3. 哈希碰撞红线（no-unsafe-hash）：
   这行配置意味着：如果你的代码里出现了MD5或者SHA-1，编译将直接失败！在 2026 年的今天，任何涉及密码或敏感凭证的散列，必须起步于SHA-256。

通过这些 Linter 规则，HarmonyOS 从代码敲下的第一秒，就把黑客可能利用的安全漏洞锁死在了摇篮里。

四、 包管理的新纪元：OHPM 与oh-package.json5

如果你有前端开发经验，你一定受够了npm庞大且臃肿的node_modules黑洞。HarmonyOS 抛弃了历史包袱，打造了专属于鸿蒙生态的包管理器——OHPM (OpenHarmony Package Manager)。

4.1 依赖声明的艺术

文件：oh-package.json5

{ "modelVersion": "6.0.2", "description": "Please describe the basic information.", "dependencies": { }, "devDependencies": { "@ohos/hypium": "1.0.25", "@ohos/hamock": "1.0.0" } }

在原生开发中，严格区分dependencies（运行时依赖）和devDependencies（开发期依赖）至关重要。
在这里，我们看到了两个鸿蒙官方的测试大杀器被引入：

• @ohos/hypium：这是鸿蒙原生的 UI 自动化测试框架。它支持在设备上模拟用户的点击、滑动，对 UI 节点进行断言，是保障高质量 App 的护城河。
• @ohos/hamock：Mock 测试框架。用于在单元测试中对底层硬件接口或网络请求进行“假数据替身”打桩。

4.2 防供应链攻击的坚实锁：oh-package-lock.json5

{ "meta": { "stableOrder": true, "enableUnifiedLockfile": false }, "lockfileVersion": 3, "ATTENTION": "THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.", "packages": { "@ohos/hamock@1.0.0": { "name": "@ohos/hamock", "version": "1.0.0", "integrity": "sha512-K6lDPYc6VkKe6ZBNQa9aoG+ZZMiwqfcR/7yAVFSUGIuOAhPvCJAo9+t1fZnpe0dBRBPxj2bxPPbKh69VuyAtDg==", "resolved": "https://ohpm.openharmony.cn/ohpm/@ohos/hamock/-/hamock-1.0.0.har" } } }

• stableOrder: true：这是为了解决多人在 Git 上提交代码时频繁发生的锁文件合并冲突。开启后，锁文件的 JSON 树结构会被强制字典序排列。
• integrity(哈希指纹防篡改)：这是防御“投毒攻击”的底线。OHPM 下载到.har包后，会计算其SHA-512哈希值并与 lock 文件对比。如果黑客黑掉了源服务器并篡改了源码包，哈希校验将直接报错阻断安装。

五、 构建流调度与本地环境：hvigorfile.ts&local.properties

5.1 操控编译流水线：Hvigor

在 Android 中构建靠 Gradle，在鸿蒙中构建靠Hvigor。

文件：hvigorfile.ts

import{appTasks}from'@ohos/hvigor-ohos-plugin';exportdefault{system:appTasks,/* Built-in plugin of Hvigor. It cannot be modified. */plugins:[]/* Custom plugin to extend the functionality of Hvigor. */}

Hvigor 是基于 TypeScript 开发的极速构建工具。system: appTasks注册了系统级的生命周期任务（如：编译 ArkTS、打包资源、生成 HAP 包）。
而留空的plugins: []则为架构师留下了无限可能：你可以自己编写一个 Hvigor 插件，在编译前自动将编译时间、Git Commit Hash 注入到代码常量中，或者在打包后自动将产物上传到远端分发平台。

5.2 绝对私密的本地隔离：local.properties

# This file is automatically generated by DevEco Studio. # Do not modify this file -- YOUR CHANGES WILL BE ERASED! # # This file should *NOT* be checked into Version Control Systems...

这段注释明确给出了开发纪律：该文件包含了你这台电脑上专有的 SDK 路径、Node.js 路径等信息。绝对不能被提交到 Git (VCS) 系统中！否则，你的同事拉下代码后，DevEco Studio 会因为找不到你的本地路径而瞬间崩溃。

六、 架构师总结：从零开始的最佳实践

要构筑一个坚不可摧、可持续迭代的千万级日活 HarmonyOS 原生应用，配置文件的管理只是第一步。基于对以上 6 个核心文件的深度拆解，为您总结鸿蒙工程初始化的“四大军规”：

1. 明确目标阵地：在build-profile.json5中死死咬住compatibleSdkVersion。不要为了使用一个炫酷的 API 而随意调高最低兼容版本，这会直接砍掉你的潜在用户群。
2. 敬畏安全红线：永远不要去修改code-linter.json5试图关闭@security的报警。如果你发现你的加密算法报错了，去重写业务层的加密逻辑，而不是去掩耳盗铃。
3. 锁定依赖生命线：将oh-package-lock.json5纳入严格的 Code Review。任何第三方库的升级必须有明确的日志记录，防止依赖链雪崩。
4. 自动化基石：善用hvigorfile.ts。在大型项目中，不要靠人力去打包签名，尽早引入 Hvigor 插件体系，实现从代码提交到打包输出的全链路自动化 CI/CD。

构建的哲学，在于在秩序中寻找自由。只有深刻理解了 HarmonyOS 底层这些晦涩的配置文件，你才能在接下来的 ArkUI 页面开发和业务流转中，做到真正的游刃有余。