OpenHarmony 采用 repo 工具统一管理数百个 Git 子仓库，掌握 repo 的拉取与编译流程是参与 OpenHarmony 开发的第一步。本文从环境准备、源码拉取、编译构建到常见问题排查，带你完整走通全流程。

---

一、环境准备

1.1 宿主机要求

推荐使用 Ubuntu 20.04 LTS 或 Ubuntu 22.04 LTS，这是社区验证最充分的平台。

硬件建议：

表格

配置项	最低要求	推荐配置
CPU	4 核	8 核及以上
内存	8 GB	16 GB 及以上
磁盘	100 GB SSD	200 GB SSD
系统	Ubuntu 20.04 LTS	Ubuntu 22.04 LTS

全量编译 OpenHarmony 是极其消耗资源的过程，资源不足会导致编译时间以小时为单位延长，甚至失败。

1.2 安装基础依赖

sudo apt-get update
sudo apt-get install -y binutils binutils-dev git git-lfs gnupg flex bison gperf \
    build-essential zip curl zlib1g-dev gcc-multilib g++-multilib \
    libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev \
    lib32z1-dev ccache libgl1-mesa-dev libxml2-utils xsltproc unzip \
    m4 bc gnutls-bin python3.8 python3-pip ruby genext2fs \
    device-tree-compiler make libffi-dev e2fsprogs pkg-config perl \
    openssl libssl-dev libelf-dev libdwarf-dev u-boot-tools mtd-utils \
    cpio doxygen liblz4-tool openjdk-8-jre gcc g++ texinfo \
    dosfstools mtools default-jre default-jdk libncurses5 apt-utils \
    wget scons tar rsync git-core libxml2-dev lib32z-dev grsync xxd \
    libglib2.0-dev libpixman-1-dev kmod

1.3 关键工具检查

Python 版本：必须使用 Python 3.8，过高或过低可能导致构建脚本不兼容。

python3 --version
# 期望输出: Python 3.8.x

git-lfs：OpenHarmony 使用 Git LFS 管理大文件（预编译工具链、二进制资源等），必须安装并初始化。

git lfs install

ccache：编译器缓存工具，能显著提升二次及后续编译速度。

export USE_CCACHE=1

1.4 配置 Git 用户信息

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
git config --global credential.helper store

1.5 安装 repo 工具

curl -s https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 > /usr/local/bin/repo
chmod a+x /usr/local/bin/repo
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple requests

 

二、源码拉取

2.1 选择拉取方式

OpenHarmony 支持 SSH 和 HTTPS 两种方式拉取源码。

表格

方式	优点	前提条件
SSH	速度快、免重复认证	需在 Gitee 添加 SSH 公钥
HTTPS	无需配置密钥	可能需要输入账号密码

SSH 公钥配置（推荐）：

# 生成 SSH 密钥（如果还没有）
ssh-keygen -t rsa -C "your-email@example.com"
# 查看公钥
cat ~/.ssh/id_rsa.pub
# 将输出的公钥内容复制到 Gitee → 个人设置 → 安全设置 → SSH公钥 → 添加公钥
# 验证连接
ssh -T git@gitee.com
# 成功会显示: Hi xxx! You've successfully authenticated...

2.2 拉取 master 主干分支

# 创建源码目录
mkdir openharmony && cd openharmony

# 初始化仓库（SSH 方式）
repo init -u git@gitee.com:openharmony/manifest.git -b master --no-repo-verify

# 或使用 HTTPS 方式
# repo init -u https://gitee.com/openharmony/manifest.git -b master --no-repo-verify

# 同步代码（-c 表示只同步当前分支）
repo sync -c

# 拉取 LFS 大文件
repo forall -c 'git lfs pull'

# 创建本地分支
repo start master --all

2.3 拉取指定 Release 版本

如果需要稳定的 Release 版本（如 OpenHarmony 4.0 Release）：

mkdir OpenHarmony_4.0_release && cd OpenHarmony_4.0_release

# 初始化指定 tag
repo init -u git@gitee.com:openharmony/manifest.git \
    -b refs/tags/OpenHarmony-v4.0-Release --no-repo-verify

# 同步代码
repo sync -c

# 拉取 LFS 大文件
repo forall -c 'git lfs pull'

# 统一切换到目标分支
repo start --all OpenHarmony-v4.0-Release

2.4 repo sync 常用参数

表格

参数	说明
-c	只同步 manifest 中指定的分支
-j<N>	使用 N 个线程并行同步，根据网络和 CPU 调整
--no-tags	不同步 tag，减少下载量
--force-sync	强制覆盖本地修改，谨慎使用

关于 -j 参数：线程数并非越大越好。数字越大拉取速度越快，但太大会导致命中率下降，反而拉取失败；太小则速度缓慢。建议根据网络带宽和 CPU 核数选择 48。

---

三、编译构建

3.1 下载预编译工具链

首次编译前，必须执行预编译脚本下载编译器及二进制工具：

bash build/prebuilts_download.sh

此步骤仅首次编译时需要执行，后续编译无需重复。

3.2 全量编译

OpenHarmony 使用 GN + Ninja 构建体系。GN 负责生成构建配置，Ninja 负责实际编译。

# 编译标准系统（如 RK3568 开发板，64位）
./build.sh --product-name rk3568 --target-cpu arm64 --ccache

# 编译标准系统（32位，不加 --target-cpu 默认 32 位）
./build.sh --product-name rk3568 --ccache

# 编译小型系统（IoT 设备）
./build.sh --product-name hi3861

# 编译迷你系统（穿戴设备）
./build.sh --product-name hi3516dv300

3.3 使用 hb 工具编译（小型/迷你系统）

对于小型和迷你系统，也可以使用 hb 命令行工具：

# 安装 hb 工具
python3 -m pip install --user build/lite
# 将 ~/.local/bin 加入 PATH
export PATH=~/.local/bin:$PATH

# 选择产品
hb set
# 用方向键选择目标产品，回车确认

# 开始构建
hb build

3.4 编译输出

编译成功后，生成的镜像位于：

out/<product-name>/packages/phone/images/

例如 RK3568 的编译产物路径为 out/rk3568/packages/phone/images/。

3.5 编译流程总览

repo sync 拉取源码
       ↓
bash build/prebuilts_download.sh（首次）
       ↓
./build.sh --product-name <产品名>
       ↓
GN 生成 Ninja 文件
       ↓
Ninja 执行编译
       ↓
输出镜像到 out/ 目录
       ↓
烧录到设备

---

四、常见问题与排查

4.1 repo sync 失败 / 网络超时

现象：同步过程中频繁断开或超时。

解决方案：

• 减少并行线程数：repo sync -c -j4
• 如果网络不稳定，可多次执行 repo sync -c，repo 会断点续传
• 使用 HTTPS 方式替代 SSH，或配置代理

4.2 SSH 权限拒绝（Permission denied）

现象：git@gitee.com: Permission denied (publickey)

解决方案：

• 确认已在 Gitee 添加 SSH 公钥
• 检查密钥文件权限：chmod 600 ~/.ssh/id_rsa
• 使用 ssh -T git@gitee.com 验证连接

4.3 Python 版本不兼容

现象：构建脚本报错，提示语法错误或模块缺失。

解决方案：

• 确保使用 Python 3.8：python3 --version
• 安装 python3.8-distutils：sudo apt install python3.8-distutils

4.4 git-lfs 大文件未拉取

现象：编译时提示找不到工具链或二进制文件。

解决方案：

git lfs install
repo forall -c 'git lfs pull'

4.5 首次编译耗时过长

现象：首次编译耗时数小时。

说明：这是正常现象。首次编译需要下载大量预编译二进制包和工具，快的也要一两个小时，慢的可能四五个小时。后续使用 --ccache 参数可显著加速。

4.6 32 位与 64 位不匹配

现象：编译成功但运行时崩溃（Crash）。

说明：系统编译为 32 位时，测试用例和组件也必须编译为 32 位，否则会导致崩溃。使用 --target-cpu arm64 指定 64 位编译。

---

五、常用 repo 命令速查

表格

命令	说明
repo init -u <url> -b <branch>	初始化仓库，指定 manifest 和分支
repo sync -c	同步代码（仅当前分支）
repo start <branch> --all	为所有子仓库创建本地分支
repo forall -c '<command>'	对所有子仓库执行命令
repo status	查看所有子仓库的修改状态
repo diff	查看所有子仓库的文件差异

---

六、总结

表格

步骤	关键命令	注意事项
环境准备	apt-get install ...	Python 3.8 + git-lfs + ccache
安装 repo	curl ... > /usr/local/bin/repo	确保可执行权限
初始化仓库	repo init -u <manifest> -b <branch>	选择正确的分支/tag
同步代码	repo sync -c	配合 git lfs pull
下载工具链	bash build/prebuilts_download.sh	仅首次需要
编译	./build.sh --product-name <name>	选对产品名是关键

掌握 repo 的拉取与编译流程后，你就可以在此基础上进行代码修改、功能开发和贡献提交了。