📚 课程目录第1章鸿蒙南向开发环境搭建

1. 鸿蒙南向开发环境搭建

说实话，很多初学者卡在第一步——环境搭建。我见过太多人，代码写好了，结果编译不过、烧录失败，最后发现是环境没配对。这一章，咱们就把这事儿彻底搞定。

我会带你走完四个关键步骤：源码获取 → 工具安装 → 编译配置 → 板子烧录。每一步我都会把坑指出来，毕竟这些坑我自己都踩过。

  本章核心目标： 让你的电脑能编译 OpenHarmony 源码，并且把固件烧到 Hi3861 开发板上跑起来。

1.1 整体流程概览

先看一张图，把整个流程串起来。你心里有个谱，后面一步步走就不慌了。

1.2 获取 OpenHarmony 源码

源码获取，我推荐用 repo 工具。为什么？因为 OpenHarmony 的仓库太多了，手动 git clone 能把你累死。repo 就是 Google 为这种多仓库项目设计的。

1.2.1 安装 repo

先确保你的 Linux 环境（我建议 Ubuntu 20.04 或 22.04）已经装好了 git 和 curl：

sudo apt-get install git curl python3 -y
mkdir -p ~/bin
curl https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 > ~/bin/repo
chmod a+x ~/bin/repo
echo 'export PATH=~/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

我的习惯： 把 repo 放到 ~/bin 下，而不是系统目录。这样换机器时，直接拷贝这个文件夹就行，不用重新配。

1.2.2 下载源码

我个人习惯把源码放在 ~/openharmony 目录下。以 OpenHarmony 3.2 Release 版本为例：

mkdir ~/openharmony && cd ~/openharmony
repo init -u https://gitee.com/openharmony/manifest.git -b refs/tags/OpenHarmony-v3.2-Release --no-repo-verify
repo sync -c -j4

-j4 表示用 4 个线程并行下载。如果你的网络好，可以改成 -j8 甚至 -j16。不过要注意——国内网络经常抽风，如果下载中断，重新执行 repo sync 就行，它会断点续传。

我曾经踩过的坑： 有一次我忘了加 --no-repo-verify，结果 repo 去验证 GPG 签名，网络超时直接失败。后来我每次 init 都带上这个参数，再也没出过问题。

1.3 安装 DevEco Device Tool

DevEco Device Tool 是华为官方提供的 IDE 插件，集成了编译、烧录、调试功能。说白了，它就是你的“一站式操作台”。

1.3.1 安装 VS Code 和插件

DevEco Device Tool 基于 VS Code，所以先装 VS Code：

sudo snap install --classic code   # Ubuntu 推荐
# 或者去官网下载 .deb 包安装

然后安装 DevEco Device Tool 插件。有两种方式：

在线安装： 在 VS Code 扩展市场搜索 "DevEco Device Tool"，点击安装。
离线安装： 去华为开发者官网下载 .vsix 包，在 VS Code 中点击 "从 VSIX 安装"。

我建议： 如果你的网络环境一般，直接下载离线包。在线安装有时候会卡在“正在下载依赖”这一步，很烦人。

1.3.2 安装编译依赖

DevEco Device Tool 装好后，还需要一些底层工具：

sudo apt-get install python3-pip scons build-essential -y
pip3 install setuptools kconfiglib pycryptodome

你想想看，这些工具链少一个，编译就会报错。我建议你对照下表检查一遍：

工具/库	版本要求	用途
Python 3	≥ 3.7	编译脚本运行环境
Scons	≥ 3.0.4	构建系统
kconfiglib	最新版	内核配置解析
pycryptodome	最新版	固件签名

1.4 配置编译环境

源码有了，工具装了，接下来就是配置编译环境。这一步的核心是 hb 工具——它是 OpenHarmony 的编译命令行入口。

1.4.1 安装 hb 工具

hb 工具在源码的 build/lite 目录下。安装命令如下：

cd ~/openharmony
python3 build/lite/hb/scripts/setup.py install

安装完成后，验证一下：

hb --version

如果能输出版本号，说明安装成功。如果提示 "command not found"，检查一下 Python 的 bin 目录有没有加到 PATH 里。

注意： 每次打开新终端，都要先 cd ~/openharmony 再执行 hb 命令。因为 hb 需要读取当前目录下的编译配置文件。我刚开始用的时候，经常在根目录下敲 hb，结果报错说找不到产品配置——后来才反应过来。

1.4.2 选择产品并编译

以 Hi3861 开发板为例，执行以下命令：

hb set
# 在弹出的菜单中选择 "wifiiot_hispark_pegasus"

选好后，开始编译：

hb build -f

-f 表示全量编译。第一次编译时间比较长，大概 10-20 分钟，取决于你的机器性能。编译成功后，你会看到类似这样的输出：

[1/1] STAMP obj/build/lite/ohos.stamp
===== build successful =====

固件生成在 out/wifiiot_hispark_pegasus/ 目录下，文件名是 Hi3861_wifiiot_app_allinone.bin。

1.5 Hi3861 开发板烧录

编译好了，最后一步就是烧录。Hi3861 支持串口烧录，我们需要用 USB 转串口模块连接开发板。

1.5.1 硬件连接

Hi3861 开发板上的串口引脚如下：

开发板引脚	USB 转串口模块
GND	GND
TX	RX
RX	TX
3.3V	VCC (3.3V)

注意交叉连接： 开发板的 TX 接模块的 RX，RX 接 TX。我第一次接的时候没注意，直接 TX 接 TX，结果烧录一直失败，还以为是板子坏了。

1.5.2 进入烧录模式

Hi3861 需要手动进入烧录模式：

按住开发板上的 BOOT 键不放。
按一下 RESET 键，然后松开。
松开 BOOT 键。

这时候，开发板就进入了烧录模式。你可以通过串口工具（如 PuTTY 或 minicom）验证——如果串口输出一堆乱码，说明连接正常。

1.5.3 使用 DevEco Device Tool 烧录

打开 VS Code，点击左侧的 DevEco Device Tool 图标。按照以下步骤操作：

点击 "PROJECT TASKS" 下的 "wifiiot_hispark_pegasus"。
选择 "Upload" 任务。
在弹出的配置窗口中，选择串口号（如 /dev/ttyUSB0）和波特率（默认 921600）。
点击 "Run" 开始烧录。

烧录过程中，你会看到进度条在跑。完成后，开发板会自动重启，运行你刚烧录的固件。

  验证方法： 打开串口监视器，波特率设为 115200。如果看到 "Hello World" 或类似的启动日志，恭喜你——环境搭建成功了！

1.6 常见问题与避坑指南

最后，我把这些年遇到的高频问题列出来，你遇到了直接对照排查：

repo sync 失败： 网络问题，换个时间段重试，或者加代理。
hb set 找不到产品： 确认你在源码根目录下执行，并且源码完整。
编译报错 "No module named 'kconfiglib'"： 用 pip3 安装 kconfiglib。
烧录时提示 "Failed to connect"： 检查串口驱动是否安装，或者开发板是否在烧录模式。
烧录后没反应： 检查串口连接是否交叉，或者固件是否编译正确。

我曾经踩过的坑： 有一次我烧录后板子没反应，排查了半天，最后发现是 USB 转串口模块的 3.3V 输出电流不够，带不动 Hi3861。换了个带独立供电的模块就好了。所以，供电问题是新手最容易忽略的。

嗯，环境搭建这部分就到这里。你跟着走一遍，应该不会有大问题。如果卡住了，回头看看上面的步骤和避坑指南，大概率能找到原因。