大家好！今天给大家介绍一个我自己折腾出来的小项目：openharmony-x86-brew。它参考了 hqzing 的 dockerharmony，把鸿蒙版 Homebrew（Harmonybrew）搬到了 x86_64 架构的 OpenHarmony 容器里。

小编荐语： OpenHarmony 的用户态可以直接跑在 Linux 内核上，社区已经有人做成了 arm64 容器镜像。这个项目把它补到了 x86_64，还在容器里装好了 brew 和编译工具链，让容器本身就是一台能从源码构建软件包的鸿蒙构建机。

研究背景：为什么要做这件事

大家好！做过鸿蒙命令行程序开发或移植的同学，大概都遇到过这几个痛点。

第一，手头没有真机，调试很不方便。社区里 hqzing 的 dockerharmony 已经解决了这一步：既然 OpenHarmony 的用户态能跑在 Linux 内核上，就把官方的 mini rootfs 打成 Docker 镜像，在 Linux 服务器上直接跑和测试命令行程序。

第二，这个镜像只支持 arm64。我们日常用的开发机、云服务器和 CI runner，很多是 x86_64，跑 arm64 镜像要靠 QEMU 软件模拟。dockerharmony 的 README 也说了，这种方式只适合快速验证，不适合日常工作。

第三，mini rootfs 太"迷你"了。它只由 musl libc、toybox 和 mksh 三样东西组成，命令行工具全靠 toybox 那一点点功能，而且 OpenHarmony 本身没有包管理器。dockerharmony 的做法是预装 curl，让你自己下载软件，并推荐用第三方的 Harmonybrew（鸿蒙版 Homebrew）。但 Harmonybrew 官方同样只支持 arm64。

所以这个项目要做的事情很明确：把 Harmonybrew 生态整体搬到 x86_64 版 OpenHarmony 上，产出一个开箱即用的镜像 dockerharmony:x86_64。思路和仓库结构都借鉴了 dockerharmony，在此感谢 hqzing 开了个好头。

方法亮点

亮点一：分阶段推进，每一步都能验证

整个移植分成 V0 到 V3 四个阶段。V0 做工具链冒烟测试，确认交叉编译的路能走通。V1 构建最小 rootfs。V2 把 brew 的引导链跑通，包括交叉编译 ruby、zsh、git，再打上 x86 补丁。V3 把编译工具链装进容器，让容器自己能编译。仓库里的 v1/、v2/、v3/ 目录和这四个阶段一一对应，所有脚本都做成了幂等的，可以反复重放，不怕中途出错。

和 dockerharmony 的对比放在一张表里：

对比项	dockerharmony	openharmony-x86-brew
架构	arm64	x86_64
包管理	无，需自行下载或另装 Harmonybrew	预置 brew 7.0.6_3 与 harmonybrew/core tap（4762 个 formula）
容器内编译	需自行准备	预置 Alpine clang 15 加 OHOS sysroot，提供 ohos-clang
基底构建方式	本地从源码构建，要求 Ubuntu 22.04 x64，至少 250GB 空间	12MB 基底 rootfs 直接放进仓库，其余由 CI 现场构建
发布方式	Docker Hub 与 ghcr.io	ghcr.io，push 触发 CI 自动发布

亮点二：ohos-clang，让容器自己当构建机

这是我觉得最有意思的一块。OpenHarmony SDK 自带的 clang 是 glibc 版本的，进不了 musl 容器。换成 Alpine 的 musl clang 15 之后，又碰到新问题：Alpine 的 LLVM 里没有 OHOS 的工具链分支，因为 SDK 里那个 clang 是 OpenHarmony 自研的 fork。

我的解法是写一个 ohos-clang 包装器，自己接管链接过程：用 -nostdlib 手动指定 OHOS 的 crt 文件和 musl 动态链接器，加上 -no-pie，编译时再显式用 -isystem 指向 multilib 头文件目录。C++ 对应的是 ohos-clang++。这样容器里就能直接编译、链接并运行 C 和 C++ 程序了。

亮点三：CI 全自动，脚本即清单

仓库里的 .github/workflows/build-image.yml 在 push 之后会自动在 ubuntu-24.04 runner 上从零构建，依次完成基底 rootfs、OHOS SDK、交叉编译、brew 引导、容器内编译工具链、真实源码构建验证和 docker 自检，最后发布到 ghcr.io。除了那个 12MB 的基底 rootfs，其余都是现场构建，所以仓库里的脚本本身就是"物料清单"，别人想复现也有据可查。

关键结果

截至 2026-10-03，V0 到 V3 已经全部打通。brew 版本是 7.0.6_3，引导链端到端可用。容器里预置了 ruby 4.0.7（rbconfig 已适配 OHOS，gem 的原生扩展可以在容器内编译）、zsh 5.9、git 2.46.0、curl 8.8.0、GNU binutils 2.44、GNU tar 1.35 和 make。

最关键的验证是：brew 已经能从上游源码构建真实软件包，并产出 x86_64_ohos 的 bottle，样品是 zlib 1.3.1。CI 的 run7 是全绿的，V3 全链路完整跑通。

使用起来很简单：

IMG=ghcr.io/zd200572/openharmony-x86-brew/dockerharmony:x86_64

# 验证 brew
docker run --rm $IMG /storage/Users/currentUser/.harmonybrew/bin/brew --version
# Homebrew 7.0.6_3-dirty

# 进入容器
docker run --rm -it $IMG /bin/zsh

容器内编译 C 程序和构建 bottle 的流程如下：

cat > hello.c <<'EOF'
#include <stdio.h>
int main(void) { printf("hello OHOS x86_64\n"); return 0; }
EOF
ohos-clang hello.c -o hello && ./hello

# 从真实上游源码构建（样例 formula 在本地 tap ohos/local）
brew install --build-bottle ohos/local/zlib
brew test ohos/local/zlib

# 出 bottle，并从 bottle 安装
brew bottle ohos/local/zlib
brew uninstall zlib && brew install /tmp/zlib-1.3.1.x86_64_ohos.bottle.tar.gz

最后一行从本地 bottle 安装，需要先设置环境变量 HOMEBREW_DEVELOPER=1，并执行 brew trust <tap>，因为 Harmonybrew 默认禁止从路径安装软件包。

小编点评：这些坑，我替你踩过了

这个项目的价值不只是"能跑"，更在于仓库里记录的踩坑清单（handoff.md 里有 32 条）。我挑几个最有代表性的讲讲，做类似移植的同学可以对号入座。

最基础的一个：Harmonybrew 在 os.sh、ld.rb 等六处硬编码了 aarch64，所以我把修改做成归档补丁放在 v2/patches/，用 apply-brew-patches.sh 幂等应用。但这里还有一个陷阱：brew update 会 checkout -f 到发布 tag，把你所有的本地修改抹掉。所以我在镜像里烘焙了 brew.env 来禁用自动更新，补丁也保持可重放。

第二个：brew 要求 ruby 的 major.minor 必须是 4.0，所以我交叉编译了 Ruby 4.0.7。同时要把 rbconfig 里的 target_os 补成 linux-ohos，不然 ruby 这一侧根本不认 OHOS。另外，rbconfig 里烤进去的是宿主机的工具链路径，要在容器内重定向到 ohos-clang 和 binutils，gem 的原生扩展（比如 prism）才能直接编译。

第三个：brew bottle 硬依赖 GNU tar 的 --hard-dereference 参数，而 toybox 的 tar 没有，所以要补装 Alpine 的 GNU tar。还有 Gemfile.lock 的平台白名单里只有 arm64 系，需要补上 x86_64-linux-ohos 和 x86_64-linux-musl，再执行 bundle lock --add-platform。

最后一个运行时的小细节：OHOS 的 musl 动态链接器不读 /etc/ld-musl-*.path，所以运行时库一律放到 /lib 下。

至于应用场景，我觉得有三类。一是在 x86 机器和 CI 上测试鸿蒙命令行程序，不用依赖 arm64 真机或 QEMU。二是给鸿蒙移植开源软件，容器里有 brew 和编译器，从源码构建再打 bottle 一条线跑通。三是给 Harmonybrew 生态补 x86_64 的支持，这也是下一步的重点。

路线图上还没做完的事有这些：把六处 x86 泛化和 V3 的四项修复提 PR 给 Harmonybrew 上游；在 harmonybrew 的 ci 仓库里加 x86_64 构建矩阵并发布 packages.x86_64_ohos.jws.json；批量构建 xz、zstd 等无依赖包，再往 ruby、python、node 这类引导包推进；还有一个可选方向，是做 OHOS 用户态加通用 Linux 内核的 x86 发行版形态。目前 bottle 仍只有 zlib 这个样品，想在容器里大规模装包，还要等 Tier-1 批量构建完成。

获取方式

项目地址：https://github.com/zd200572/openharmony-x86-brew

参考项目 dockerharmony：https://github.com/hqzing/dockerharmony

Harmonybrew 项目主页：https://atomgit.com/Harmonybrew

镜像直接拉取：ghcr.io/zd200572/openharmony-x86-brew/dockerharmony:x86_64