面向x86 QEMU运行环境的OpenHarmony系统镜像构建踩坑记录

摘要

本文记录了在Ubuntu 20.04环境下，基于OHOS Porting Communities（OPC）的移植代码，成功编译构建适用于x86 QEMU的OpenHarmony 6.0-Release系统镜像的完整过程。文章重点分享了在构建过程中遇到的典型问题、排查思路及解决方案，旨在为后续开发者提供一份实用的避坑指南。

1 前言

OpenHarmony作为一款面向全场景的开源分布式操作系统，其官方文档主要围绕ARM架构设备进行介绍。对于希望在常见的x86平台（如标准PC）上进行学习、测试和开发的爱好者而言，直接使用官方主线代码在x86 QEMU上获得完整体验仍存在一定门槛。

社区力量在此时显得尤为重要。OHOS Porting Communities (OPC) 等社区项目提供了对x86架构更为完善的适配补丁和构建支持，极大地降低了入门难度。本文旨在记录笔者使用OPC代码完成OpenHarmony x86 QEMU镜像构建的实战经历，重点聚焦于构建阶段（非运行时）的关键配置、资源要求以及遇到的典型错误及其解决方案。关于QEMU的运行与调试，将在后续文章中专题探讨。

笔者说明：本文侧重点在于"构建"过程本身，希望帮助大家更平滑地跨过编译这道坎。所有操作在Ubuntu 20.04 LTS下验证通过。

2 环境准备与资源评估

“工欲善其事，必先利其器。” 在开始编译前，充分的准备是成功的一半。

2.1 硬件与时间成本预估

基于实战经验，以下数据供你在开始前建立合理的预期：

资源类型	最低配置	推荐配置	个人实践（两种环境）
磁盘空间	200 GB 剩余	200 GB+ 剩余	编译后总占用约 190 GB
物理内存	16 GB	32 GB 或更多	16 GB (N100小主机) / 64 GB (华为云ECS)
编译时间	约20-30小时	取决于CPU核心数与并行任务数	约24小时 (N100) / 7-8小时 (16核ECS)
网络环境	稳定，能访问Gitee/GitCode	高速，用于快速拉取数十GB代码	依赖Gitee/GitCode代码托管平台

核心建议：

• 磁盘空间务必留足：编译过程会产生大量中间文件，空间不足是导致编译失败最常见的原因之一。建议保留200GB以上的磁盘空间。
• 使用--ccache：在构建命令中加入此参数，可以显著加速二次及后续的编译速度。
• 时间规划：首次编译非常耗时，请合理安排在长时间不关机的环境下进行。

2.2 系统与基础工具链

OPC推荐使用Ubuntu 20.04系统环境。如果宿主机是其他系统或版本，使用Docker构建一个一致的环境是很好的选择。

安装必备的系统工具和编译依赖，以下命令比OPC基础清单更完善，涵盖了笔者实践中发现的额外必需工具：

sudo apt-get update && sudo apt-get install -y autoconf autotools-dev automake libtool build-essential gcc-multilib bin86 gdb curl libx11-dev binutils gnupg flex bison gperf zip zlib1g-dev g++-multilib libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev lib32z1-dev ccache libgl1-mesa-dev libxml2-utils xsltproc unzip m4 bc gnutls-bin python3.8 python3-pip ruby default-jdk libssl-dev libtinfo5 genext2fs u-boot-tools mtools mtd-utils scons abootimg libelf-dev libxcursor-dev libxrandr-dev libxinerama-dev lz4 cpio pkg-config

注意：其中 lz4, cpio, pkg-config 在纯净Docker环境中可能缺失，提前安装可避免后续构建意外中断。

3 构建流程关键步骤

3.1 配置开发环境

1. 设置Git用户信息：

git config --global user.name "Your Name"

git config --global user.email "your-email@example.com"

git config --global credential.helper store

2. 安装并配置Repo工具：

mkdir ~/bin

curl https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 -o ~/bin/repo

chmod a+x ~/bin/repo

# 确保 ~/bin 在 PATH 环境变量中

echo 'export PATH=~/bin:$PATH' >> ~/.bashrc

source ~/.bashrc

pip3 install -i https://repo.huaweicloud.com/repository/pypi/simple requests

3.2 获取源码与预编译工具

1. 初始化并同步代码仓库：
   使用OPC维护的manifest仓库，指定OpenHarmony-6.0-Release分支。

export PROJ_ROOT=/home/yourname/OpenHarmony/6.0-release # 自定义你的工作目录

mkdir -p $PROJ_ROOT

cd $PROJ_ROOT

repo init -u https://gitee.com/ohos-porting-communities/manifest.git-b OpenHarmony-6.0-Release --no-repo-verify

repo sync -c

repo forall -c 'git lfs pull'

2. 下载预编译工具链：
   在源码根目录下执行官方脚本，以下载编译器、库文件等必要资源。

cd $PROJ_ROOT

bash build/prebuilts_download.sh

3.3 构建前的关键调整

此部分为经验总结，能有效预防已知问题。

1. 调整系统Shell解释器：
   Ubuntu默认使用dash作为/bin/sh的链接，而OpenHarmony的构建脚本针对bash编写。为避免潜在语法兼容性问题，需切换：

sudo dpkg-reconfigure dash

在弹出的对话框中选择 No，将默认Shell设置为bash。

2. 升级Node.js版本以避免告警：
   在下载预编译工具阶段，prebuilts_download.sh脚本会下载Node.js的三个版本，分别是：14.21.1、16.20.2、18.20.1，并在编译阶段使用其中一个版本。构建系统默认使用较旧的Node.js v14，会触发版本过低的警告，要求使用v18及以上的版本。修改根目录下的build.sh脚本，将：

EXPECTED_NODE_VERSION="14.21.1"

改为

EXPECTED_NODE_VERSION="18.20.1"

同时，由于Node.js版本升级，需将代码中所有：

npm config set lockfile false

修改为：

npm config set package-lock false

否则在编译开始后会报错 ：

npm ERR! lockfile is not a valid npm option。

4 编译执行与产出

完成所有配置后，执行以下命令开始构建：

./build.sh --product-name x86_general --ccache --gn-args=is_qemu=true

当终端最终输出 =====build x86_general successful. 时，恭喜你！编译成功。生成的系统镜像文件位于 out/x86_general/packages/phone/images/ 目录下，主要包括：

• bzImage（内核镜像）
• system.img（系统镜像）
• userdata.img（用户数据镜像）
• vendor.img（供应商镜像）
• ramdisk.img（内存磁盘镜像）

这些镜像文件即可用于QEMU启动。

5 典型问题与解决

在构建过程中，可能会遇到以下问题：

5.1 头文件缺失错误（如 fatal error: 'ievent_filter.h' file not found）

这类问题通常是由于大型项目并行编译时产生的依赖顺序问题。虽然错误提示头文件缺失，但实际检查发现文件是存在的。

• 解决方案：简单地重新运行构建命令往往可以解决。

./build.sh --product-name x86_general --ccache --gn-args=is_qemu=true

笔者在遇到该错误时，通过再次执行编译命令后问题消失。

6 总结与预告

本文详细记录了在x86架构上构建OpenHarmony QEMU镜像的全过程，涵盖了环境准备、代码获取、工具配置、常见问题排查等关键环节。希望这份实践记录能为你的OpenHarmony探索之路节省宝贵的时间。

然而，构建成功只是第一步。在下一篇文章中，我们将进入更具挑战性的环节：如何在QEMU中成功启动这个镜像。。在笔者的实践中，就遇到了鼠标输入失灵的问题。下一篇文章将会就启动镜像的部分进行描述，敬请期待。

参考资料

1. OHOS Porting Communities (OPC) 官方仓库
2. OpenHarmony 官方文档