第一章 鸿蒙南向开发环境搭建

做鸿蒙南向开发，第一步就是把环境搭起来。说实话，这一步卡住了不少人。我刚开始接触 OpenHarmony 时，光编译环境就折腾了两天。后来总结出一套相对顺手的流程，今天分享给你。

1.1 OpenHarmony 源码获取

源码获取是第一步。OpenHarmony 的代码托管在 Gitee 上，和华为内部仓库保持同步。我个人习惯用 repo 工具来管理多仓库项目，鸿蒙的代码结构确实复杂，不用 repo 会非常痛苦。

这里有个坑。我曾经在同步时网络不稳定，导致部分仓库没拉下来。建议加 --no-clone-bundle 参数，能避免一些奇怪的网络问题。另外，-j4 表示 4 个线程并行下载，如果你电脑性能好，可以改成 -j8 甚至 -j16。

1.2 编译环境配置（Ubuntu + Docker）

编译环境我强烈推荐用 Docker。为什么？因为鸿蒙的编译依赖链非常复杂，不同版本对 Python、GCC、Make 的版本要求都不一样。用 Docker 可以做到环境隔离，换项目时不会互相污染。

我团队里有个新人，直接在宿主机上装编译环境，结果把系统 Python 搞坏了，重装了三次系统。后来我让他用 Docker，再没出过类似问题。

1.2.1 安装 Docker

# 卸载旧版本
sudo apt remove docker docker-engine docker.io containerd runc

# 安装依赖
sudo apt install apt-transport-https ca-certificates curl software-properties-common

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

# 添加稳定版仓库
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

# 安装 Docker
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

# 验证安装
sudo docker run hello-world

1.2.2 拉取鸿蒙编译镜像

华为官方提供了编译镜像，省去了自己配置环境的麻烦。

# 拉取标准编译镜像
docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0

# 创建容器并挂载源码目录
docker run -it -v /path/to/ohos:/home/openharmony \
  swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0 /bin/bash

1.2.3 编译验证

进入容器后，执行一次全量编译，验证环境是否正常。

# 进入源码目录
cd /home/openharmony

# 安装编译依赖（首次需要）
pip3 install --user build/lite

# 设置编译目标（以 Hi3861 为例）
hb set -p hi3861

# 开始编译
hb build -f

第一次编译会比较慢，大概 20-30 分钟。如果看到 BUILD SUCCESS，说明环境没问题了。

1.3 Hi3861 / Hi3516 开发板介绍

这两块板子是鸿蒙南向开发最常用的硬件平台。我手头各有三块，平时调试基本够用。

特性	Hi3861	Hi3516
CPU	ARM Cortex-M4 @ 160MHz	ARM Cortex-A7 @ 900MHz
内存	352KB SRAM	64MB DDR3
存储	2MB Flash	32MB SPI Flash
无线	2.4G Wi-Fi	无（需外接）
典型场景	IoT 传感器、智能家居	摄像头、智能网关
操作系统	LiteOS-M	LiteOS-A / Linux

Hi3861 是 MCU 类芯片，资源有限，适合做轻量级设备。Hi3516 是应用处理器，能跑 Linux，适合做带屏幕或摄像头的产品。

我记得第一次用 Hi3861 时，发现它的 Flash 只有 2MB，编译出来的镜像稍微大一点就烧不进去。后来学会了裁剪组件，把不需要的模块去掉，才把镜像控制在 1.5MB 以内。

1.4 烧录工具使用

烧录工具这块，不同芯片用的工具不一样。Hi3861 用 HiBurn，Hi3516 用 HiTool。两个工具都是华为提供的，界面风格类似。

1.4.1 Hi3861 烧录（HiBurn）

1. 下载 HiBurn 工具（华为开发者网站可获取）
2. 用 USB 线连接开发板和电脑，安装驱动（CH340 或 CP2102）
3. 打开 HiBurn，选择串口和波特率（建议 921600）
4. 点击 Connect，按住开发板上的 RST 键，再按 PRG 键进入烧录模式
5. 选择编译好的 .bin 文件，点击 Burn

1.4.2 Hi3516 烧录（HiTool）

1. 打开 HiTool，选择 Hi3516DV300 芯片型号
2. 切换到 烧写eMMC 标签页
3. 加载编译生成的 u-boot.bin、bootargs、kernel.img、rootfs.img 等文件
4. 设置网口参数（IP 地址、子网掩码、网关）
5. 点击 烧写，给开发板上电

Hi3516 的烧录比 Hi3861 复杂一些，因为它需要烧录多个分区。我建议第一次烧录时，把 擦除所有 选项勾上，避免旧数据干扰。

1.5 知识体系总览

下面这张图把本章的核心流程串起来了。你可以把它当作一个检查清单，每完成一步就对照一下。