3、开发环境搭建（二）：源码获取与首次全量编译
上一章我们把基础工具链装好了，但真正的代码还没拿到手。这一章咱们就干三件事：从 Gitee 把源码拉下来、把编译需要的几个运行时环境配好、然后跑一次完整的全量编译。
说实话，我第一次搭 OpenHarmony 环境时，最头疼的就是版本匹配问题。Python 版本不对、Node.js 版本太新、SCons 找不到……各种报错能把人整崩溃。所以这一章我会把那些坑都指出来，你跟着走就行。
3.1 从 Gitee 获取源码
OpenHarmony 的源码托管在 Gitee 上，用的是 repo 工具管理多仓库。你想想看，一个操作系统涉及几百个 Git 仓库，要是手动一个一个 clone，那得搞到猴年马月去。
3.1.1 安装并配置 repo
repo 是 Google 开发的 Git 仓库管理工具，OpenHarmony 社区做了适配。安装很简单：
# 创建 bin 目录并加入 PATH
mkdir -p ~/bin
export PATH=~/bin:$PATH
# 下载 repo 工具
curl -s https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 > ~/bin/repo
chmod a+x ~/bin/repo
# 配置 Git 用户信息（如果还没配）
git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"
export PATH=~/bin:$PATH 写到 ~/.bashrc 里，这样每次打开终端就不用重新 export 了。
3.1.2 初始化并同步源码
选一个代码分支很重要。OpenHarmony 有多个发布版本，我建议初学者用最新的 LTS 版本，稳定且文档齐全。
# 创建工作目录
mkdir -p ~/openharmony
cd ~/openharmony
# 初始化 repo（以 4.0 Release 为例）
repo init -u https://gitee.com/openharmony/manifest.git -b OpenHarmony-4.0-Release --no-repo-verify
# 同步全部源码
repo sync -c -j4
-j4 表示用 4 个线程并行下载，如果你的电脑性能好、网速快，可以改成 -j8 甚至 -j16。不过要注意，有些老旧路由器扛不住太多并发连接，会断流。
repo sync 会中断。别慌，重新执行一次就行，repo 会断点续传。如果反复失败，试试 repo sync -c --no-tags 跳过标签下载，能省不少流量。
同步完成后，源码目录大概长这样：
| 目录/文件 | 说明 |
|---|---|
kernel/ |
LiteOS 内核代码 |
foundation/ |
系统基础能力（分布式、图形、AI 等） |
device/ |
设备适配层，各芯片厂商的 BSP |
vendor/ |
产品配置和 OEM 定制 |
build/ |
编译构建框架和脚本 |
out/ |
编译产物输出目录（首次编译后生成） |
3.2 编译环境配置
源码拿到了，但编译还跑不起来。OpenHarmony 的构建系统依赖三个关键工具：Python、Node.js 和 SCons。缺一个都不行，版本不对也不行。
3.2.1 Python 环境
OpenHarmony 4.0 要求 Python 3.8 以上，但不要用 Python 3.12，有些依赖包还没适配。我个人推荐 3.9 或 3.10。
# 检查当前 Python 版本
python3 --version
# 如果版本不对，用 apt 安装指定版本
sudo apt-get install python3.9 python3.9-venv python3.9-dev
# 设置默认 Python 版本（可选）
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.9 1
然后安装 Python 依赖包：
# 进入源码根目录
cd ~/openharmony
# 安装编译所需的 Python 包
pip3 install --user setuptools
pip3 install --user kconfiglib
pip3 install --user pycryptodome
pip3 install --user ecdsa
sudo pip3 install，会污染系统 Python 环境。加 --user 参数安装到用户目录，干净又安全。
3.2.2 Node.js 环境
Node.js 主要用于前端相关的构建任务，比如 JS 框架的编译和打包。OpenHarmony 4.0 需要 Node.js 14.x 或 16.x。
# 安装 Node.js 16.x
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs
# 验证版本
node --version # 应该显示 v16.x
npm --version # 应该显示 8.x 或 9.x
安装完成后，配置 npm 镜像源，不然下载依赖包会慢到怀疑人生：
npm config set registry https://registry.npmmirror.com
3.2.3 SCons 构建工具
SCons 是 OpenHarmony 的底层构建引擎，用 Python 写的。安装很简单：
pip3 install --user scons
# 验证安装
scons --version
SCons 版本要求 3.1.2 以上，但不要太新。我记得有一次我装了 SCons 4.5，结果构建脚本报了一堆语法错误，折腾了半天才发现是版本兼容问题。
3.3 首次全量编译
环境配好了，终于可以编译了。第一次编译会下载一些预编译工具链和依赖库，所以需要联网。
3.3.1 选择编译目标
OpenHarmony 支持多种开发板。我们以官方的 Hi3861（Wi-Fi IoT 模组）为例，这个板子资源占用小，编译快，适合第一次跑通流程。
# 设置编译目标
hb set
# 在弹出的菜单中选择 "wifiiot_hispark_pegasus"
hb 是 OpenHarmony 的编译命令行工具，在源码根目录下执行 source build/envsetup.sh 后就能用了。
3.3.2 执行全量编译
# 编译
hb build -f
-f 表示全量编译（full build）。第一次编译大概需要 10-30 分钟，取决于你的电脑配置。编译过程中会看到大量日志输出，别慌，这是正常的。
编译成功后，最后几行输出大概是这样：
...
[1/1] STAMP obj/build/lite/ohos.stamp
===== build wifiiot_hispark_pegasus successful. =====
编译产物在 out/hispark_pegasus/wifiiot_hispark_pegasus/ 目录下，主要文件有：
OHOS_Image.bin：系统镜像文件OHOS_Image.map：内存映射文件（调试用）OHOS_Image.asm：反汇编文件（分析用）
全量编译 vs 增量编译：
- 全量编译（
hb build -f）：从头编译所有代码，第一次或修改了构建配置时用。 - 增量编译（
hb build）：只编译修改过的文件，日常开发用这个，快很多。
3.4 本章知识结构
下面这张图把本章的核心流程串起来了，你可以对照着检查自己走到哪一步了：
3.5 常见编译错误排查
第一次编译很少能一次通过，我把最常见的几个错误列出来，你遇到了直接对照着查：
| 错误现象 | 可能原因 | 解决办法 |
|---|---|---|
python3: command not found |
Python 未安装或未加入 PATH | 安装 Python 3.9，检查 /usr/bin/python3 是否存在 |
ModuleNotFoundError: No module named 'kconfiglib' |
Python 依赖包未安装 | 执行 pip3 install --user kconfiglib |
node: not found |
Node.js 未安装或版本不对 | 安装 Node.js 16.x，确认 node --version 正常 |
scons: command not found |
SCons 未安装 | pip3 install --user scons |
hb: command not found |
未 source 环境变量 | 执行 source build/envsetup.sh |
SSL certificate problem |
Git 证书问题或网络代理 | git config --global http.sslverify false（临时） |
好了，到这里你应该已经拿到了源码，配好了环境，并且成功跑完了第一次全量编译。这个过程虽然有点繁琐，但只要你跟着步骤走，遇到问题对照上面的表格排查，一定能搞定。