这一章不教你技术，教你怎么用这本书。
如果你急着动手，至少读完「二、开工前自检」和「三、需要准备什么」再往下翻。

========================================

一、这本书适合谁

1.1 如果你符合下面任意两条，这本书就是给你写的

• ☐ 学过一点 C 语言，能让单片机跑起来（哪怕只是点过流水灯）
• ☐ 想知道"鸿蒙"到底是什么，但搜到的资料要么是新闻稿、要么是厂商宣传
• ☐ 想做软硬结合的东西——不是纯写 App，也不是纯画电路板
• ☐ 看着官方文档觉得"每个字都认识，连起来不知道在说啥"
• ☐ 想找一个能从头跟到尾的项目，而不是一堆零散的 Demo
• ☐ 是电子信息 / 物联网 / 嵌入式相关专业，想给自己找条路

1.2 如果你是这样，这本书可能不适合你

• 想三天速成找工作。 这本书从点灯讲到分布式，正常速度要三到五个月。
• 只想抄代码跑通就行。 这本书有大量"为什么"，如果你只想"怎么做"，会觉得很啰嗦。
• 已经有多年 Linux 驱动经验。 直接看官方文档更快，本书第 01–05 章对你太浅。
• 想学的是纯 App 开发、完全不碰硬件。 那第 03–05 章（环境搭建、驱动、总线）可以跳过，但说实话有点可惜。

1.3 这本书不假定你有以下任何一项

但有一件事这本书假定你会：愿意动手，并且接受前几个小时会很挫败。

二、开工前自检：你现在缺什么

对照下面这张表，**缺什么补什么，别硬闯。**硬闯的结果就是第 03 章卡三天然后放弃。

2.1 知识自检

最重要的一条：C 语言。
南向开发 80% 的代码是 C。你不需要精通，但指针和结构体必须懂——否则第 04 章的 device->priv、第 10 章的 void *data 会让你彻底懵掉。

2.2 心态自检

这本书的路线是这样的：

第 01–02 章   看懂，不动手        ← 轻松，像读小说
第 03 章      【劝退率最高】       ← 一整章都在装环境、排报错
第 04–05 章   开始有正反馈        ← 灯亮了、数据读出来了
第 06–08 章   上手快，成就感强     ← 界面能点了
第 09–10 章   难度回升            ← 分布式和 NAPI 是全书的坎
第 11–12 章   收尾，做出成品      ← 最爽

第 03 章是一道墙。 我见过太多人倒在这里。

如果你在第 03 章卡住了，请记住：

环境搭建的坑，跟你的能力没关系，跟运气有关系。
每个人机器不一样、网络不一样、系统版本不一样，踩的坑都不一样。
老手也会卡，只是他们知道卡住该去哪儿找答案。

翻到本章第七节「卡住了怎么办」，照着做。

三、需要准备什么

3.1 硬件清单（按推荐顺序买）

最低配置预算：约 ¥100（板子 + 线 + 面包板 + 传感器 + 万用表 + 电阻）

三个新手最容易买错的坑：

1. 买了不能传数据的 USB 线（只能充电）——认准"数据线"三个字
2. 买了裸片传感器而不是模块——SHT30 裸片是那种芝麻大的贴片，你焊不上。买"模块"，就是带引脚插面包板的那种
3. 不买万用表——这是全表性价比最高的东西。灯不亮的时候，万用表能在 30 秒内告诉你是不是硬件问题

3.2 软件清单

硬盘：至少留 100 GB，建议 150 GB。
内存：8 GB 起步。CPU：4 核起步。

四、全书路线图

这张图是全书骨架。迷路的时候就回来看它。

┌─────────────────────────────────────────────────────────┐
│  第 00 章  写在前面          ← 你在这儿                    │
│            认清目标、备齐装备、知道往哪走                    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  第一阶段 · 看懂（01–02 章）    不动手，纯理解              │
│                                                          │
│  01 鸿蒙初开   三个"鸿蒙"有什么区别、架构长什么样            │
│  02 三种身法   内核是谁、为什么能大能小                     │
│  ── 产出：你能跟别人讲清楚鸿蒙是什么 ──                     │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  第二阶段 · 南向（03–05 章）    C 语言，靠近硬件            │
│                                                          │
│  03 铸剑       装环境、编固件、烧板子      【劝退墙】        │
│  04 点灯       GPIO 与第一个驱动                          │
│  05 五脏六腑   I2C/SPI/UART/PWM/ADC 与中断                │
│  ── 产出：一块能读温湿度的开发板 ──                         │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  第三阶段 · 北向（06–08 章）    ArkTS，靠近用户             │
│                                                          │
│  06 北向初见   ArkTS 语言 + 声明式 UI + 状态管理             │
│  07 舞台       Stage 模型、生命周期、路由                   │
│  08 内外兼修   数据、网络、权限、通知、后台任务               │
│  ── 产出：一个能装、能用、不丢数据的 App ──                  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  第四阶段 · 打通（09–10 章）    全书最难，也最值钱           │
│                                                          │
│  09 分身术     分布式软总线、跨端迁移、设备虚拟化             │
│  10 南北打通   NAPI：让 ArkTS 和 C 直接对话                │
│  ── 产出：一个手机能直接读开发板传感器的软硬结合产品 ──        │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  第五阶段 · 出师（11–12 章）                               │
│                                                          │
│  11 出师       包结构、签名、上架、元服务、就业方向            │
│  12 造物者     完整项目收尾 + 全书复盘                      │
│  ── 产出：一个能放进简历的东西 ──                           │
└─────────────────────────────────────────────────────────┘

每个阶段都有明确的产出。 没有产出就别往下走——那说明前面没消化。

五、三种读法：按你的目标选

读法 A：全栈型（推荐，也最累）

全读，按顺序，每章做完练习。

• 耗时：3–5 个月（业余时间）
• 适合：想把这条路走通、想靠这个找工作的
• 结果：能独立完成软硬结合项目

读法 B：只做硬件 / 南向

读 00–05，然后跳到 10、11。

• 耗时：1.5–2 个月
• 适合：电子/嵌入式背景，以后想做驱动、做固件
• 注意：第 10 章（NAPI）一定要读，哪怕你不写 App——因为你要知道怎么把接口交给别人用
• 结果：能给鸿蒙设备写驱动、适配外设

读法 C：只做应用 / 北向

读 00–02（挑着看），然后 06–09、11。跳过 03–05。

• 耗时：1.5–2 个月
• 适合：有编程基础，不想碰烙铁
• 但请至少读一遍 04 和 05 —— 不要求你做，但要知道你的 App 底下那块板子是怎么干活的。这会让你在技术讨论里跟别人不一样
• 结果：能写鸿蒙原生应用

三种读法的重叠区：

   A 全栈   ████████████████████████   (00→12 全读)
   B 南向   ███████████           ██   (00-05, 10-11)
   C 北向   ██            ███████ ██   (00-02, 06-09, 11)
            ↑             ↑      ↑
          01-02        06-09   10-11

六、怎么读这本书

6.1 三条建议

第一，先跑通，再追问为什么。

每一章的代码，先原样抄一遍、跑起来、看到结果，然后再回头研究每一行的意思。

很多概念你第一遍看不懂很正常——**等你看到东西动起来了，再回头看，往往一下就懂了。**反过来（先弄懂每一行再动手）是新手最容易陷入的死循环。

第二，每一章都要做出一个能演示的东西。

❌ 错误：读完第 05 章，"嗯，我知道 I2C 是怎么回事了"
✅ 正确：读完第 05 章，"我的板子每两秒打印一次温湿度，串口能看到"

**看十遍不如做一遍。**你以为懂了和真的能做出来，中间隔着一道巨大的鸿沟。

第三，遇到不懂的名词，先跳过。

这本书里有些地方会提前用到后面才讲的概念。**第一次遇到不认识的词，记下来，继续往下读。**很多时候读到后面，前面的疑问自己就解开了。

如果读完整章还是不懂——翻到本章第七节，或者搜。

6.2 关于代码

本书所有代码都遵循这些约定：

⚠️ 最重要的一条：不要指望复制粘贴就能跑通。
不同 SDK 版本的函数名、参数、头文件路径可能不一样。
学会看报错、学会查头文件、学会搜——这三件事比记住 API 重要一百倍。

七、卡住了怎么办

这是全书最实用的一节。 建议你在第 03 章卡住的时候回来重读。

7.1 排错心法：从简单到复杂

新手遇到问题的第一反应通常是"代码错了"，然后开始逐行检查代码。

这是效率最低的做法。 正确的顺序是从最简单、最物理的那一层开始：

   第 1 层：物理层 —— 线插了吗？电有吗？
   ├─ 电源灯亮吗？
   ├─ USB 线是数据线还是充电线？
   ├─ 杜邦线有没有松动 / 插错孔？
   └─ 用万用表量一下 VCC 和 GND 之间是不是该有的电压
        ↑ 30% 的问题在这里

   第 2 层：连接层 —— 电脑认得板子吗？
   ├─ 设备管理器里有没有出现串口（COMx）？
   ├─ 虚拟机有没有把 USB 透传进去？
   ├─ 驱动装了吗（CH340 / CP210x）？
   └─ 串口号选对了吗？
        ↑ 再 30% 的问题在这里

   第 3 层：工具层 —— 工具用对了吗？
   ├─ 波特率对吗？（一般 115200）
   ├─ 烧录模式进去了吗？（按 RST 了吗？）
   ├─ 选的固件路径是最新的吗？
   └─ 编译的产品选对了吗？（hb set）
        ↑ 再 20% 在这里

   第 4 层：代码层 —— 逻辑对吗？
   ├─ 代码真的编进去了吗？（BUILD.gn 加了吗？上层 features 加了吗？）
   ├─ 引脚号对吗？
   ├─ 初始化函数调用了吗？
   └─ 延时单位对吗？（osDelay 是 tick 不是毫秒！）
        ↑ 只有剩下的 20% 在这里

记住这个比例：80% 的问题不在代码里。

7.2 五步自救法

遇到报错，按顺序做这五件事：

第一步：完整读一遍报错信息。

我知道它又长又红又吓人，但——90% 的报错里面已经写了原因。

比如这行：
fatal error: iot_gpio.h: No such file or directory

翻译：找不到 iot_gpio.h 这个头文件
原因已经写在脸上了：要么是路径没配对，要么是这个头文件根本不存在

第二步：复制报错原文去搜。

不要自己组织语言描述问题。就复制原文，整行复制。

❌ 搜索："鸿蒙编译找不到头文件怎么办啊"
✅ 搜索："fatal error: iot_gpio.h: No such file or directory"

你踩的坑，全网踩过的人成千上万。你不是一个人在战斗。

第三步：确认"最简单的部分"是对的。

灯不亮 → 先用杜邦线把那个脚直接接 VCC，看灯亮不亮。
读不到传感器 → 先写个 I2C 扫描程序，看能不能找到设备地址。
网络不通 → 先 ping 一下。

先证明最简单的那部分是对的，再怀疑复杂的部分。

第四步：二分法定位。

如果不知道问题出在哪一段，就砍掉一半。

代码跑不起来？
  → 只留初始化，其他全注释掉 → 能跑吗？
     ├─ 能 → 问题在被注释掉的那部分，再砍一半
     └─ 不能 → 问题在初始化，继续砍

第五步：睡一觉。

这不是玩笑。很多折腾三小时没解决的问题，第二天早上十分钟就找到了。

疲劳会让你反复检查同一个地方，却看不见明显的错误。

7.3 求助的正确姿势

如果你要问别人，这样问能让你得到答案的概率提高十倍：

❌ 差的提问：
"我的板子跑不起来，求大佬看看"
（没人知道你遇到的是什么问题）

✅ 好的提问：
【目标】想让 Hi3861 读 SHT30 的温湿度
【现象】串口一直打印 "read failed, ret=-1"
【已确认】
  · 上拉电阻 4.7k 已接
  · I2C 扫描能找到 0x44
  · 单独调用 IoTI2cWrite 也返回 -1
【代码】（贴关键 10 行，不要贴 500 行）
【报错】（贴完整原文）

四要素：目标 / 现象 / 已确认 / 代码+报错原文。

更重要的是——"已确认"那一栏经常能让你自己找到答案。 因为写下来的过程中你会重新检查一遍。

7.4 去哪儿找答案

7.5 四种常见死局

死局一：环境死活装不上

• 症状：编译一直报错，换了好几种方法都不行
• 解法：虚拟机快照回滚，重来一次。或者——先跳过南向，去第 06 章学北向（DevEco Studio 装起来比南向简单得多）。不要在一堵墙上撞死。

死局二：代码一模一样，别人能跑我不能跑

• 症状：照着教程抄的，就是不行
• 解法：99% 是版本不一致。查你的 SDK 版本，查你的开发板型号，查你的引脚定义。书里写的是逻辑，你的环境是具体的。

死局三：前几天还好好的，突然不行了

• 症状：什么都没改，突然就坏了
• 解法：想想你最后改了什么。 如果确定没改代码，那就是硬件——线松了、板子供电不足、传感器坏了。换根线试试。

死局四：完全不知道该从哪下手

• 症状：太难了，看不懂，想放弃
• 解法：回到上一章的产出，确认它是好的。 然后往前走一小步——只做最小的一步，跑通了再走下一步。你不是不行，你只是步子迈太大了。

八、本书的约定

8.1 术语约定

8.2 关于版本

这本书里的 API 名字、文件路径、命令参数，可能会随着版本变化。

这不是书写错了，是这个领域本身就在快速迭代。遇到对不上的地方：

1. 查你手上 SDK 的头文件（最快）
2. 查对应版本的官方文档
3. 搜索报错原文

书里讲的是"为什么"和"怎么做"，这些不会变。 变的只是具体函数名。

8.3 关于合规

这本书教的是如何构建，不是如何破坏。

所有涉及"修改别人的东西"的技术，请只用在：

• ✅ 你自己写的代码
• ✅ 你自己拥有的设备
• ✅ 明确授权你测试的环境
• ✅ 开源项目

不要用在：别人的应用、商业软件、付费内容、任何你不拥有或者没有授权的东西。

老陈在第 12 章留下的三条铁律里，最后一条就是这条。技术越高，这条线越重要。

九、出发前最后一句话

这本书的路线，是从点亮一盏灯开始，到做出一个能放进简历的东西结束。

中间你会经历：

• 第 03 章的挫败（几乎每个人都会）
• 第 04 章灯亮时那一下子的开心
• 第 05 章第一次读到传感器数据时的"卧槽真的可以"
• 第 06 章写界面时的顺畅
• 第 09/10 章的重新卡住
• 第 12 章做完时的那种"我真的做出来了"

这些都是正常的。 卡住不代表你不行，只代表这一段需要多花点时间。

翻到下一页，我们开始。

=================剧情片段=================

助理：导演，第 00 章就这么结束了吗？一章都没讲技术。

导演：这一章讲的东西比技术重要。

助理：为什么？

导演：因为新手弃坑，90% 不是因为技术太难，是因为不知道自己在哪、要往哪走、卡住了该怎么办。

助理：所以这一章是……

导演：地图、装备清单、和一份"我卡住时的自救手册"。

助理：可是急着动手的人会跳过这一章吧？

导演：会。然后在第 03 章卡死，回来重读这一章。

助理：（笑）那为什么要放在最前面？

导演：因为我希望有人的第 03 章，能过得稍微顺一点。

========================================

本章自检

• ☐ 我知道这本书适不适合我，以及我该选哪种读法
• ☐ 我对照第二节做了自检，知道自己缺什么、要补多久
• ☐ 我知道要买哪些东西，预算大概是多少
• ☐ 我看过第四节的全书路线图，知道五个阶段各自产出什么
• ☐ 我知道遇到问题时，按"物理层→连接层→工具层→代码层"的顺序排查
• ☐ 我知道求助时要给出"目标 / 现象 / 已确认 / 代码+报错原文"

下一章：第 01 章 · 鸿蒙初开 —— 先搞清楚你到底要学的是哪个"鸿蒙"。