一、知识体系总览
鸿蒙开发完整知识体系，不是只会写页面，而是要形成完整能力链：环境搭建、ArkTS 语言、ArkUI 组件、Stage 应用模型、系统能力、数据架构、测试调试、性能安全、发布运营。
鸿蒙应用开发
基础：环境和工程
能力扩展：ArkTS + ArkUI
工程化：Stage + 系统能力 + 数据
生产实践：质量、性能、安全、发布治理
DevEco Studio
SDK / 模拟器 / 真机
AppScope / entry / resources
类型系统 / 模块化 / 异步
组件 / 布局 / 状态 / 列表
UIAbility / WindowStage / Context
权限 / 网络 / Preferences / Repository
测试 / 日志 / 性能
隐私 / 合规 / 上架 / 监控
二、详细知识点
1. DevEco Studio
DevEco Studio 是鸿蒙应用开发的核心 IDE，负责创建项目、下载 SDK、编辑 ArkTS、预览界面、管理模拟器、签名、编译和调试。基础阶段最重要的是先创建一个最小 Stage 模型工程并运行成功，不要一开始就堆复杂能力。
工程要求：
- 能区分 IDE 问题、SDK 问题、项目配置问题和设备连接问题。
- 能解释 Debug 签名和 Release 签名差异。
- 能在多人协作中固定 SDK、依赖和构建脚本版本。
2. SDK 与 API 版本
鸿蒙项目的 compileSdkVersion 决定编译时 API，compatibleSdkVersion 决定兼容目标。项目导入失败时，第一步检查本机安装 SDK 是否与 build-profile.json5 匹配。
3. Stage 模型工程结构
text
AppScope/app.json5 应用级信息：包名、图标、版本
entry/src/main/module.json5 模块级信息：Ability、权限、入口
entry/src/main/ets/entryability UIAbility 生命周期入口
entry/src/main/ets/pages 页面
entry/src/main/ets/components 组件
entry/src/main/ets/model 数据模型
entry/src/main/ets/services 业务服务、缓存、状态封装
entry/src/main/resources 字符串、颜色、图片等资源4. HAP 与模块
HAP 是 Harmony Ability Package。简单应用通常只有 entry 一个模块；复杂应用可以拆多个 feature 模块。可上线工程要关注模块边界、依赖方向、公共模型复用、构建速度和发布包体。
5. 资源管理
字符串、颜色、图标不要散落在页面里。资源统一管理便于国际化、深色模式、品牌改版和多设备适配。
三、本章 demo
Demo 1：最小应用配置
demo/harmony-news-demo/AppScope/app.json5
json5
{
"app": {
"bundleName": "com.example.harmonynews",
"vendor": "example",
"versionCode": 1000000,
"versionName": "1.0.0",
"icon": "$media:app_icon",
"label": "$string:app_name"
}
}Demo 2：入口 Ability
demo/harmony-news-demo/entry/src/main/ets/entryability/EntryAbility.ets
ts
windowStage.loadContent('pages/Index', (err) => {
if (err.code) {
hilog.error(0x0000, 'HarmonyNews', 'loadContent failed')
return
}
hilog.info(0x0000, 'HarmonyNews', 'loadContent success')
})Demo 3：当前机器可运行验证
bash
cd /Users/liuyinghui/Documents/harmonyOS/harmonyos-knowledge-system/demo/web-preview
node server.js浏览器打开 http://127.0.0.1:4173，如果能看到新闻列表并点击详情，说明核心业务 demo 可以运行。
四、面试题与详细答案
1. HarmonyOS Stage 模型工程最关键的文件有哪些？
关键文件包括 AppScope/app.json5、entry/src/main/module.json5、EntryAbility.ets、页面 pages/*.ets 和资源目录。app.json5 管应用级元信息，module.json5 管模块、Ability、权限和入口，EntryAbility.ets 管生命周期和首页加载，页面文件负责 UI，资源目录负责字符串、颜色和媒体资源。
追问：为什么页面路径错会白屏？因为 WindowStage.loadContent() 根据页面路径加载 ArkUI 页面，路径错误时窗口无法渲染首页。
2. compileSdkVersion 和 compatibleSdkVersion 有什么区别？
compileSdkVersion 是编译时使用的 API 版本，决定代码能引用哪些接口；compatibleSdkVersion 是兼容目标，影响应用在目标系统上的兼容性判断。导入他人项目时，如果本机 SDK 缺失，常见现象是同步或编译失败。
3. 学习者为什么要先跑通空项目？
因为鸿蒙开发链路包含 IDE、SDK、签名、模拟器、设备连接、构建脚本等多个环节。如果空项目都不能运行，继续写业务代码只会放大问题。先跑通空项目可以把环境问题和业务问题分开。
4. 可上线工程和基础 demo 的差别是什么？
基础 demo 关注功能跑通；可上线工程关注可维护、可测试、可扩展、可观测和可发布。具体表现是模块边界清晰、资源统一、错误可追踪、权限最小化、性能可验证、发布流程可复现。
五、五倍扩展知识点矩阵
1. 学习路线完整知识体系
| 层级 | 学习目标 | 必须掌握 | 实操产出 | 质量判断标准 |
|---|---|---|---|---|
| 基础 1 | 知道鸿蒙应用是什么 | DevEco、SDK、ArkTS、ArkUI | 创建空项目 | 能解释项目为什么能启动 |
| 基础 2 | 能运行默认页面 | 模拟器、真机、签名 | 首页显示文本 | 能定位环境和代码问题边界 |
| 基础 3 | 能读懂目录结构 | AppScope、entry、resources | 修改应用名和图标 | 能说明每个配置文件职责 |
| 基础 4 | 能创建页面 | pages、loadContent |
新增页面 | 能处理页面路径错误 |
| 能力扩展 1 | 能组织小型应用 | pages/components/model/services | 新闻 demo | 能避免页面臃肿 |
| 能力扩展 2 | 能做状态驱动页面 | @State、列表、按钮 |
收藏功能 | 能说明状态来源 |
| 能力扩展 3 | 能做多设备布局 | 手机、平板、横竖屏 | 自适应列表 | 能处理窗口变化 |
| 工程化 1 | 能做真实业务接入 | 网络、权限、缓存 | Repository | 能处理失败和重试 |
| 工程化 2 | 能做工程治理 | 模块、版本、依赖 | 工程规范 | 能控制依赖方向 |
| 质量保障 | 能做质量保障 | 测试、日志、调试 | 验收清单 | 能复现并定位问题 |
| 发布治理 | 能做发布治理 | 签名、隐私、上架 | 发布包 | 能解释合规风险 |
| 长期维护 | 能做长期维护 | 监控、性能、回归 | 迭代计划 | 能降低长期维护成本 |
2. 环境安装深度清单
| 项 | 基础理解 | 工程化理解 | 质量关注点 |
|---|---|---|---|
| DevEco Studio | 写代码和运行 | 管 SDK、模拟器、签名 | 固定团队版本、减少环境漂移 |
| SDK Manager | 下载 API 和工具 | 管多版本 SDK | 项目版本和本机版本可追踪 |
| Emulator | 模拟设备 | 覆盖不同尺寸 | 与真机差异要记录 |
| 真机调试 | USB 连接运行 | 开发者模式、授权 | 权限和硬件能力真机验证 |
| 签名 | 让应用可安装 | Debug/Release 差异 | 发布证书管理和权限隔离 |
| HAP | 模块包 | 多模块拆分 | 包体、依赖、启动路径治理 |
| AppScope | 应用级配置 | 版本、图标、包名 | 发布标识不可随意变更 |
| module.json5 | 模块能力 | Ability、权限、设备类型 | 权限最小化和能力边界 |
| resources | 资源管理 | 多语言、多主题 | 品牌、无障碍、国际化治理 |
| build-profile | 构建配置 | SDK、target、product | CI 构建一致性 |
3. 工程目录生产实践解读
AppScope 不是普通资源目录，它表达应用身份。bundleName 一旦用于发布和生态能力绑定，就不应随意改变。versionCode 应按发布流水线单调递增，versionName 面向用户展示，两者职责不同。
entry 是入口模块，但不等于所有代码都要放在入口模块。随着业务增长，可以拆分 feature 模块、common 模块和能力模块。可上线工程会把"可复用代码"和"页面入口代码"分开，防止 entry 成为巨型模块。
resources/base 是应用体验一致性的基础。字符串、颜色、图片如果散落在页面中，会导致后期国际化、深色模式和品牌改版成本成倍增加。
4. 版本和兼容策略
| 场景 | 错误做法 | 正确做法 |
|---|---|---|
| 新项目导入失败 | 直接改代码 | 先看 SDK 版本和构建配置 |
| 团队多人协作 | 每个人本机随意升级 SDK | 文档中固定可用 SDK 版本 |
| 升级 API | 一次性改所有模块 | 先建升级分支和回归清单 |
| 支持旧设备 | 只看编译通过 | 做真实兼容验证 |
| 发布回滚 | 只保留最新包 | 保存构建产物、签名和版本记录 |
5. 运行链路拆解
Index 页面 WindowStage EntryAbility HarmonyOS 用户点击应用 Index 页面 WindowStage EntryAbility HarmonyOS 用户点击应用 创建 UIAbility onCreate 创建窗口舞台 loadContent("pages/Index") 构建 ArkUI 页面 展示首页
启动失败排查顺序：应用配置、模块配置、Ability 路径、页面路径、页面构建错误、资源引用错误、SDK/签名/设备问题。
六、环境与工程 demo 扩展任务
| 任务 | 操作 | 验证 | 对应能力 |
|---|---|---|---|
| 修改应用名 | 改 string.json 的 app_name |
启动后标题变化 | 资源管理 |
| 修改图标 | 替换 app_icon.svg |
桌面图标变化 | 媒体资源 |
| 新增颜色 | 在 color.json 添加颜色 |
页面引用成功 | 资源引用 |
| 新增页面 | 创建 AboutPage.ets |
可跳转显示 | 页面组织 |
| 生命周期日志 | 在 EntryAbility 打日志 |
前后台有日志 | Stage 生命周期 |
| 模拟器运行 | DevEco 启动模拟器 | 应用可安装 | 环境 |
| 真机运行 | USB 连接授权 | 应用可打开 | 真机调试 |
| 平板预览 | 切换 tablet 设备 | 布局不溢出 | 多设备 |
| 签名检查 | 配置 Debug 签名 | 可安装运行 | 签名 |
| 构建检查 | 同步工程后构建 | 无配置错误 | 工程构建 |
七、常见故障与定位
| 现象 | 高概率原因 | 定位方式 | 修复 |
|---|---|---|---|
| DevEco 无法同步 | SDK 不匹配 | 看 Sync 日志 | 安装对应 SDK 或调整配置 |
| 启动白屏 | 页面路径错 | 检查 loadContent |
修正 pages/Index |
| 图标不显示 | media 资源缺失 | 查 $media: 名称 |
补资源或改引用 |
| 应用名不变 | 字符串资源没改对 | 查 $string: |
改正确资源项 |
| 真机装不上 | 签名或授权问题 | 看安装日志 | 重新签名和授权 |
| 模拟器卡住 | 镜像或资源不足 | 看模拟器状态 | 换镜像或释放资源 |
| 运行按钮灰色 | 模块配置异常 | 看 run configuration | 重新选择 entry |
| 编译 API 报错 | SDK 缺接口 | 查 API 版本 | 升级 SDK 或降级接口 |
| 权限声明无效 | 放错配置位置 | 查 module.json5 |
移到正确模块 |
| 路径大小写问题 | 文件名不一致 | 查真实文件名 | 保持大小写一致 |
八、扩展面试题
5. AppScope 和 entry 的边界是什么？
AppScope 表达应用级身份，例如包名、版本、图标和标签；entry 是具体入口模块，包含 Ability、页面、资源和模块配置。把二者分开可以让应用身份和业务入口解耦。多模块项目中，其他模块可以提供能力，但应用身份仍由 AppScope 管理。
6. 为什么大型鸿蒙项目不能只有一个 entry 模块？
所有代码都放在 entry 会导致编译慢、依赖混乱、模块边界不清、测试困难。大型项目应该按业务域或能力域拆分模块，例如 common、network、account、feature-news。拆分后要控制依赖方向，避免 feature 之间互相引用。
7. 如何设计鸿蒙学习路线最稳？
先跑通空项目，再理解工程结构；再学习 ArkTS 和 ArkUI；随后做 Stage 生命周期、导航、网络、缓存、权限；最后补测试、性能、安全和发布。不要一开始就直接做复杂系统能力，因为环境和基础 UI 都没稳时，排错成本会很高。
8. 导入别人项目失败时你会怎么排查？
先看 DevEco 和 SDK 版本，再看 build-profile.json5，然后看模块配置、依赖、签名和设备。不要先改业务代码。能同步失败通常是环境或构建配置，能编译但启动失败才更可能是 Ability、页面或资源问题。
9. 为什么工程化开发要记录环境版本？
移动端工程高度依赖 IDE、SDK、构建插件和设备环境。版本不记录会导致"我这里能跑，你那里不能跑"。工程团队会在 README、CI 或构建配置中固定关键版本，并在升级时写清楚兼容风险。
10. HAP 和应用安装包是什么关系？
HAP 是鸿蒙能力模块包。简单应用可能只有一个 entry HAP；复杂应用可以有多个 HAP 或模块。发布时要关注模块组合、包体大小、权限声明和入口能力配置。
九、知识点详解库
1. 环境不是一次性工作
很多学习者把环境搭建看成"装好 IDE 就结束"，但生产项目中环境是持续治理对象。SDK 升级、DevEco Studio 升级、签名证书更新、模拟器镜像变化、团队成员机器差异都会影响构建和运行。工程团队会把环境版本写进 README，并把升级过程当成一次工程变更。
2. SDK 版本要和项目生命周期绑定
短期 demo 可以使用本机最新 SDK，长期项目要明确当前支持的 SDK 范围。升级 SDK 可能带来 API 行为变化、构建插件变化或设备兼容问题。正确做法是建立升级分支，先跑核心流程，再更新文档和 CI。
3. 模拟器验证不能替代真机验证
模拟器适合快速开发和布局调试，但真机才覆盖真实硬件、传感器、性能、权限弹窗、后台策略和系统版本差异。发布前至少要用目标设备形态做真机核心路径验证。
4. Debug 签名和 Release 签名的风险不同
Debug 签名用于开发调试，Release 签名用于发布。不要把调试证书、调试包、测试接口和日志开关带到生产环境。签名证书要有权限和备份管理，否则证书丢失会影响后续发布。
5. 入口模块不能承担所有职责
entry 模块是应用入口，但随着业务变多，应把公共能力、网络、数据、业务特性拆出去。拆分不是为了形式，而是为了减少耦合、提升构建效率、降低多人协作冲突。
6. 配置文件是运行契约
app.json5、module.json5 和 build-profile.json5 不只是构建材料，它们决定应用身份、Ability 声明、权限、设备类型和构建目标。配置和代码不一致时，代码写对也可能运行失败。
7. 资源命名要可维护
资源名应表达用途而不是颜色值本身，例如 color_primary 比 blue_176b87 更容易维护。后续换品牌色时，语义命名只改资源值，页面代码不需要跟着改。
8. 应用能力要从第一天开始记录
项目即使是 demo，也应该写清楚目标设备、核心功能、权限需求、运行方式和验证路径。这些信息会在后续扩展时成为工程边界，避免"越写越像临时代码"。
9. 工程入口要便于新人接手
一个好的鸿蒙工程入口应该让新人 10 分钟内知道如何打开、如何运行、核心页面在哪里、数据从哪里来、遇到构建失败先看什么。README 和目录命名就是项目可维护性的一部分。
10. 版本号不是随便写的
versionCode 面向系统和发布流水线，应递增；versionName 面向用户，应表达版本含义。生产发布中，版本号会和崩溃、灰度、回滚、用户反馈绑定，不能随意复用。
11. 设备类型声明影响能力边界
deviceTypes 不只是展示信息。声明支持 phone/tablet 后，就要承担对应布局、交互和兼容验证责任。声明越多，测试面越大。
12. 空项目运行成功是最小闭环
空项目运行成功说明 IDE、SDK、构建、签名、模拟器或真机链路基本可用。后续任何业务问题都可以以这个闭环为基准排查。
十、环境实战场景库
| 场景 | 目标 | 操作 | 验收 |
|---|---|---|---|
| 新人接手 | 10 分钟跑通 | 按 README 打开 demo | 首页出现 |
| SDK 缺失 | 定位环境问题 | 对照 build-profile.json5 |
SDK 补齐 |
| 页面白屏 | 定位页面路径 | 查 loadContent |
页面恢复 |
| 图标替换 | 理解媒体资源 | 改 app_icon.svg |
图标变化 |
| 应用改名 | 理解字符串资源 | 改 app_name |
名称变化 |
| 平板运行 | 验证设备类型 | 选择 tablet | 布局可用 |
| 真机调试 | 验证真实设备 | USB 运行 | 安装成功 |
| 签名失败 | 理解签名链路 | 检查签名配置 | 可安装 |
| 版本升级 | 理解版本语义 | 修改版本号 | 构建记录变化 |
| 模块拆分 | 理解工程演进 | 新增 common 模块 | 依赖清晰 |
| 资源缺失 | 理解资源引用 | 删除再恢复资源 | 错误可定位 |
| 构建失败 | 建立排错顺序 | 先环境后代码 | 修复路径明确 |
十一、扩展面试题库
11. 为什么 README 是工程质量的一部分？
README 不是装饰文档，而是项目入口。它决定新人能否快速运行、测试人员能否找到验收路径、维护者能否理解目录和构建要求。没有 README 的项目，交接成本会很高。
12. 环境问题和代码问题如何区分？
先运行空项目或已知可用项目。如果空项目也失败，优先查 IDE、SDK、签名和设备；如果空项目成功而当前项目失败，再查项目配置、依赖、页面路径和业务代码。
13. 为什么资源要集中管理？
集中管理能支持多语言、深色模式、品牌改版和统一视觉。硬编码资源会让修改散落在页面中，增加遗漏和不一致风险。
14. 多设备支持为什么要谨慎声明？
声明支持某设备意味着要保证该设备上的布局、交互和能力可用。没有经过验证就声明，会带来用户体验和发布质量风险。
15. 如何规划鸿蒙项目的第一周学习？
第一天跑通环境，第二天读懂目录，第三天写页面和组件，第四天做状态和列表，第五天做 Stage 生命周期，第六天接入服务层和缓存，第七天补测试、排错和总结。
十二、完整知识域补全
官方知识地图按开发者任务旅程组织内容，覆盖准备、体验设计、架构、质量、工具、功能开发、测试、上架与分发。当前文档包按这个旅程重新对齐，避免只停留在页面 demo。
| 知识域 | 必须掌握的内容 | 对应文档 | 必须产出 |
|---|---|---|---|
| 开发准备 | DevEco Studio、SDK、模拟器、真机、账号、签名、HAP | 01 | 可运行工程 |
| 工程结构 | AppScope、entry、Feature HAP、resources、build-profile | 01 | 目录说明和构建说明 |
| 语言基础 | ArkTS 类型、类、接口、泛型、异步、异常、模块 | 02 | 类型模型和 Service |
| UI 框架 | ArkUI 组件、布局、状态、导航、动画、手势、绘制 | 03 | 页面和组件库 |
| 应用模型 | Stage、UIAbility、WindowStage、Context、Want、ExtensionAbility | 04 | 生命周期和路由设计 |
| 数据能力 | Preferences、文件、关系型数据库、缓存、Repository | 04 | 数据访问层 |
| 系统能力 | 权限、网络、通知、媒体、位置、后台任务、卡片 | 04 | 能力封装层 |
| 多设备 | 响应式布局、折叠屏、平板、分布式/协同场景 | 03/04 | 多端适配方案 |
| 质量保障 | 单测、UI 测试、专项测试、调试、日志、DevEco Testing | 05 | 测试矩阵 |
| 性能体验 | 启动、列表、内存、功耗、包体、弱网、无障碍 | 05 | 性能清单 |
| 安全合规 | 权限最小化、隐私说明、日志脱敏、敏感数据保护 | 05 | 安全清单 |
| 发布运营 | 签名、版本、AGC、分阶段发布、回滚、监控 | 05 | 发布门禁 |
| 架构设计 | 模块边界、依赖方向、状态管理、数据流、可观测性 | 04/05 | 架构图和约束 |
十三、鸿蒙工程能力全景图
鸿蒙应用工程能力
开发环境
语言与编译
声明式 UI
应用模型
数据与系统能力
多端体验
质量与发布
架构治理
DevEco Studio
SDK / Previewer / Emulator
签名 / HAP / AGC
ArkTS 类型系统
模块化与依赖
异步、并发、错误边界
组件与布局
状态管理
导航、动画、手势、绘制
UIAbility
WindowStage
ExtensionAbility
Want / Context
网络与权限
Preferences / 文件 / 数据库
通知 / 媒体 / 位置 / 后台任务
手机 / 平板 / 折叠屏
响应式布局
分布式和协同场景
测试与调试
性能与安全
上架、灰度、回滚
分层架构
模块边界
可观测、可测试、可演进
十四、项目目录应如何演进
简单 demo 可以只有 entry，但业务增长后需要拆分：
text
harmony-news/
AppScope/
entry/ # 应用入口、壳工程、首页装配
feature-news/ # 新闻列表、详情、搜索、分类
feature-favorite/ # 收藏、阅读历史
feature-settings/ # 主题、字号、隐私开关
common-ui/ # 通用组件、主题、图标、空状态
common-model/ # 领域模型、DTO、错误模型
common-data/ # Repository、缓存、数据库、网络
common-platform/ # 权限、通知、日志、设备能力
test-fixtures/ # 测试数据和 mock 服务拆分原则：
entry只做应用入口和页面装配，不承载全部业务。feature-*按业务域拆，不互相直接依赖。common-*放稳定公共能力，不能反向依赖业务模块。- 数据层不依赖 UI，UI 层不直接依赖底层系统 API。
- 每个模块都要有 README，说明职责、依赖和可测试点。
十五、能力验收清单
| 能力 | 自测问题 | 合格表现 |
|---|---|---|
| 环境 | 换一台机器能否跑起来 | README 写清 SDK、打开方式和运行方式 |
| 工程 | 新人能否找到入口 | AppScope、module、EntryAbility、pages 职责清楚 |
| 配置 | 权限和设备类型是否准确 | module.json5 与实际能力一致 |
| 资源 | 颜色、字符串、图标是否集中 | 页面没有大量硬编码 |
| 构建 | 是否能区分 debug/release | 签名、版本、构建模式有说明 |
| 演进 | 业务变多后是否能拆模块 | 有模块边界和依赖规则 |
| 交付 | 是否能证明核心流程可用 | 有 demo、验收路径和错误处理 |