鸿蒙 PC 搭建 Harmonybrew 贡献开发环境指南（融合开发引擎 + DockerHarmony + OpenDesk）

qq_57467750

19人浏览 · 2026-08-18 10:03:49

qq_57467750 · 2026-08-18 10:03:49 发布

鸿蒙 PC 搭建 Harmonybrew 贡献开发环境指南（融合开发引擎 + DockerHarmony + OpenDesk）

适用场景：在鸿蒙 PC 上搭建 harmonybrew 开发环境，用于编写 Formula、本地编译测试、提交 PR 贡献软件包。

前置条件：一台鸿蒙 PC（HUAWEI MateBook Pro 等），系统版本 HarmonyOS 6.1+。

文档说明：本文档记录了从零开始的完整部署流程，每一步都附带成功时的实际日志输出，可作为人工部署指南，也可作为 AI Agent 的参考文档。

整体架构
启动融合开发引擎
在融合开发引擎中安装 Podman
拉取并运行 DockerHarmony 容器
容器内安装 zsh
容器内安装 Harmonybrew
容器内安装开发工具链 devel-base
容器内安装 openssh
配置 Git 和 SSH 密钥
注册 AtomGit 并 Fork 仓库
克隆 Fork 并配置上游仓库
创建环境启动脚本
容器内安装 Node.js 和 OpenDesk
环境验证清单
日常使用流程
常见问题

1. 整体架构

鸿蒙 PC（宿主机）
├── 融合开发引擎（官方提供的 Linux 虚拟机）
│   ├── Linux 内核（支持 cgroup2）
│   ├── dnf 包管理器
│   └── Podman（容器运行时）
│       └── DockerHarmony 容器
│           ├── 用户态 = OpenHarmony musl libc + toybox
│           ├── 内核 = Linux（虚拟机提供）
│           ├── uname → "Linux"（软件自动匹配 Linux 构建路径）
│           ├── harmonybrew + ohos-sdk + 工具链
│           └── 你在这里写 Formula、编译、测试、提交 PR
│
├── GitNext（宿主机上的，不用管）
└── DevBox（宿主机上的，不用管）

为什么需要在容器中开发？

原因	原生鸿蒙 PC	DockerHarmony 容器
内核身份	HongMeng，`uname` hack 不全	真 Linux 内核，零死角
musl libc	原版有 HiLog 噪声	改过，stderr 干净
CI 对齐	环境 ≠ CI，可能反复返工	同镜像，本地过 = CI 过
文件系统	HMDFS 不支持符号链接	普通文件系统
环境隔离	装的工具污染宿主机	销毁即净

容器与宿主机的二进制兼容性：

编译出来的包能在原生鸿蒙 PC 上运行，因为：

CPU 指令集相同：两者都是 aarch64
C 库兼容：两者都用 musl libc（容器修改版仅去除了内部 HiLog 日志，API/ABI 不变）
内核系统调用兼容：HongMeng 内核实现了 Linux 兼容的 syscall 接口
编译产物是动态链接的，运行时使用宿主机的 musl libc

2. 启动融合开发引擎

2.1 什么是融合开发引擎

融合开发引擎是鸿蒙 PC 官方提供的 Linux 虚拟机功能。鸿蒙 PC 原生环境无法使用 Docker 和 Podman，但在融合开发引擎中可以使用 Podman 来运行容器。

注意：融合开发引擎中也因为缺少内核选项而无法使用 Docker，但 Podman 是可用的。

2.2 启动步骤

在鸿蒙 PC 桌面或应用列表中找到"融合开发引擎"应用
点击启动，进入 Linux 虚拟机终端
验证环境：

uname -a

预期输出（应显示 Linux 内核，而不是 HongMeng Kernel）：

Linux localhost ... aarch64 ...

判断标准：如果 uname -a 输出包含 HarmonyOS ... HongMeng Kernel，说明你还在原生鸿蒙环境里，没有进入融合开发引擎。你需要从桌面找到并启动融合开发引擎应用。

3. 在融合开发引擎中安装 Podman

操作位置：融合开发引擎虚拟机终端（提示符类似 [user@localhost ~]$）

3.1 创建 Podman 配置文件

sudo mkdir -p /etc/containers

sudo tee /etc/containers/storage.conf << 'EOF' > /dev/null
[storage]
# 驱动设置为 vfs
driver = "vfs"
# 设置 runroot
runroot = "/run/containers/storage"
# 设置数据持久化目录
graphroot = "/var/lib/containers/storage"

[storage.options]
# 关键：确保这一行被注释掉（前面加 #），或者是空的
# mount_program = "/usr/bin/fuse-overlayfs"
EOF

3.2 安装 Podman

sudo dnf update -y
sudo dnf install podman -y

3.3 创建并挂载 cgroup

sudo mkdir -p /sys/fs/cgroup
sudo mount -t cgroup2 cgroup2 /sys/fs/cgroup

参考：此配置方法参考了 B 站用户 @零炻分享的飞书笔记：https://my.feishu.cn/wiki/FnmSwU70jihXLtkJ1zKcICeenVc

4. 拉取并运行 DockerHarmony 容器

操作位置：融合开发引擎虚拟机终端

4.1 拉取镜像

sudo podman pull ghcr.io/hqzing/dockerharmony:latest

4.2 启动容器

sudo podman run \
  -itd \
  --name=ohos \
  --network=host \
  --cgroup-manager=cgroupfs \
  --pids-limit=-1 \
  ghcr.io/hqzing/dockerharmony:latest

关键参数说明：

--network=host：容器使用宿主机网络（必须）
--cgroup-manager=cgroupfs：使用 cgroupfs 管理器（兼容性更好）
--pids-limit=-1：不限制进程数

4.3 进入容器

sudo podman exec -it ohos sh

预期输出：

进入容器后，提示符变为 #（root 用户）。验证容器环境：

uname -a

预期输出：

Linux ... aarch64 ...

重要：后续所有操作（第 5 步到第 13 步）都在容器内（# 提示符）进行，不要在融合开发引擎虚拟机终端（[user@localhost ~]$ 提示符）中操作。容器使用 musl libc，鸿蒙二进制只能在容器中运行，不能在虚拟机中运行。

4.4 关于 DockerHarmony 容器

DockerHarmony 是一个最小化 OpenHarmony 容器，不是 ci-runner 镜像：

DockerHarmony（公开的，你刚拉的）         ci-runner（不公开）
├── 最小化 OpenHarmony 系统              ├── 基于 DockerHarmony 构建
├── 只有 toybox 基础命令 + curl          ├── 预装 harmonybrew + ohos-sdk
├── 什么开发工具都没有                    ├── 预装 make/perl/GNU 工具链
└── 你需要自己往里装东西                  └── 存在华为云 SWR，不对外公开

容器内默认只有：

toybox 提供的少量基础命令
内置的 curl
sh（toybox 提供）

没有 zsh、git、make、编译器等开发工具，需要手动安装。

5. 容器内安装 zsh

操作位置：DockerHarmony 容器内（# 提示符）

Harmonybrew 安装脚本需要 zsh，容器内默认没有，需要先安装。

5.1 下载 zsh

从 Harmonybrew 项目的 GitHub Releases 下载鸿蒙版 zsh：

curl -fsSL -o /tmp/zsh.tar.gz https://github.com/Harmonybrew/ohos-zsh/releases/download/5.9/zsh-5.9-ohos-arm64.tar.gz

注意 URL：是 releases（r-e-l-e-a-s-e-s），不是 realeases（多一个 a）。

5.2 解压

tar xzf /tmp/zsh.tar.gz -C /

解压后的目录结构：

/zsh-5.9-ohos-arm64/
├── bin/
│   ├── zsh
│   └── zsh-5.9
└── share/
    └── zsh/
        └── 5.9/
            └── functions/
                └── ...（补全函数等）

5.3 创建符号链接

ln -s /zsh-5.9-ohos-arm64/bin/zsh /usr/bin/zsh
ln -s /zsh-5.9-ohos-arm64/bin/zsh-5.9 /usr/bin/zsh-5.9

5.4 验证

/zsh-5.9-ohos-arm64/bin/zsh --version

预期输出：

zsh 5.9 (aarch64-unknown-linux-gnu)

然后验证 PATH 中的 zsh：

zsh --version

预期输出：

zsh 5.9 (aarch64-unknown-linux-gnu)

排错：如果 zsh --version 报 cannot execute: required file not found，说明你可能在融合开发引擎虚拟机中操作而不是在容器内。鸿蒙二进制需要 musl libc（容器中有，虚拟机中没有 glibc 兼容）。请确认你在容器内（# 提示符）操作。

6. 容器内安装 Harmonybrew

操作位置：DockerHarmony 容器内（# 提示符）

6.1 运行安装脚本

zsh -c "$(curl -fsSL https://harmonybrew.atomgit.com/install.sh)"

预期输出（关键部分）：

==> This script will install:
/storage/Users/currentUser/.harmonybrew/bin/brew
/storage/Users/currentUser/.harmonybrew/share/doc/homebrew
...
==> Downloading and installing Homebrew by curl...
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  115M  100  115M    0     0  5578k      0  0:00:21  0:00:21 --:--:-- 7037k
==> Downloading https://harmonybrew.atomgit.com/bottles/portable-git-2.55.0.arm64_ohos.bottle.tar.gz
==> Pouring portable-git-2.55.0.arm64_ohos.bottle.tar.gz
==> Updating Homebrew...
==> Downloading https://harmonybrew.atomgit.com/bottles/portable-ruby-4.0.5_1.arm64_ohos.bottle.tar.gz
==> Pouring portable-ruby-4.0.5_1.arm64_ohos.bottle.tar.gz
...
==> Installation successful!

==> Next steps:
- Run these commands in your terminal to add Homebrew to your PATH:
    echo >> /root/.mkshrc
    echo 'eval "$(/storage/Users/currentUser/.harmonybrew/bin/brew shellenv)"' >> /root/.mkshrc
    eval "$(/storage/Users/currentUser/.harmonybrew/bin/brew shellenv)"

6.2 配置环境变量

echo >> ~/.zshrc
echo 'eval "$(/storage/Users/currentUser/.harmonybrew/bin/brew shellenv)"' >> ~/.zshrc

eval "$(/storage/Users/currentUser/.harmonybrew/bin/brew shellenv)"

6.3 验证

brew --version

预期输出：

Homebrew 6.0.6_11

7. 容器内安装开发工具链 devel-base

操作位置：DockerHarmony 容器内（# 提示符）

7.1 安装 devel-base

devel-base 是一个级联依赖包，安装后会自动拉取 ohos-sdk（LLVM 编译器）、llvm-gcc-compat（cc/gcc 软链接）、make、coreutils 等一整套编译工具：

brew install devel-base

预期输出（关键部分）：

==> Would install 1 formula:
devel-base
==> Would install 22 dependencies for devel-base:
gmp
coreutils
diffutils
mpfr
ncurses
readline
gawk
gnu-sed
gnu-tar
gpatch
zlib-ng-compat
bzip2
pcre2
grep
gzip
ohos-sdk
llvm-gcc-compat
make
libunistring
gdbm
perl
texinfo
==> Do you want to proceed with the installation? [y/n]
==> Fetching downloads for: devel-base
✔︎ Bottle gmp (6.3.0)                                 Downloaded    1.1MB/  1.1MB
✔︎ Bottle coreutils (9.11)                            Downloaded    3.6MB/  3.6MB
...
✔︎ Bottle ohos-sdk (26.0.0.18_1)                      Downloaded  777.7MB/777.7MB
...
==> Installing devel-base dependency: ohos-sdk
==> Pouring ohos-sdk-26.0.0.18_1.arm64_ohos.bottle.tar.gz
🍺  /storage/Users/currentUser/.harmonybrew/Cellar/ohos-sdk/26.0.0.18_1: 51,065 files, 2.7GB
...
==> Installing devel-base
==> Pouring devel-base-1.0.1.arm64_ohos.bottle.tar.gz
🍺  /storage/Users/currentUser/.harmonybrew/Cellar/devel-base/1.0.1: 6 files, 24.7KB
==> Running `brew cleanup devel-base`...

注意：ohos-sdk 体积较大（约 778MB），下载和安装需要几分钟，请耐心等待。

排错：文件锁错误

如果安装过程中途取消（如误按 Ctrl+C 或 Ctrl+Z），再次执行 brew install devel-base 时可能报错：
Error: A `brew install devel-base` process has already locked /root/.cache/Homebrew/downloads/xxx--ohos-sdk-xxx.bottle.tar.gz.incomplete.
Please wait for it to finish or terminate it to continue.
原因：上一次的 brew 进程被挂起，锁文件还在。

解决：
# 杀掉挂起的进程
kill %1 2>/dev/null

# 删除锁文件
rm -f /root/.cache/Homebrew/downloads/*.incomplete

# 重新安装
brew install devel-base

7.2 验证工具链

which cc gcc clang make

预期输出：

/storage/Users/currentUser/.harmonybrew/bin/cc
/storage/Users/currentUser/.harmonybrew/bin/gcc
/storage/Users/currentUser/.harmonybrew/bin/clang
/storage/Users/currentUser/.harmonybrew/bin/make

clang --version

预期输出：

clang version 15.0.4 (/srv/workspace/llvm-release/2026_0313_llvm15_release/toolchain/llvm-project/clang 0e01a01d567b9acfce8edfdadb66a7b69f088fb0)
Target: aarch64-unknown-linux-ohos
Thread model: posix
InstalledDir: /storage/Users/currentUser/.harmonybrew/Cellar/ohos-sdk/26.0.0.18_1/native/llvm/bin

make --version

预期输出：

GNU Make 4.4.1
Built for aarch64-unknown-linux-gnu
Copyright (C) 1988-2023 Free Software Foundation, Inc.
...

8. 容器内安装 openssh

操作位置：DockerHarmony 容器内（# 提示符）

需要 openssh 来生成 SSH 密钥和连接 AtomGit：

brew install openssh

9. 配置 Git 和 SSH 密钥

操作位置：DockerHarmony 容器内（# 提示符）

9.1 设置 PATH

容器内的默认 shell 是 sh（toybox），PATH 需要手动配置才能找到 git：

export PATH=/storage/Users/currentUser/.harmonybrew/Homebrew/Library/Homebrew/vendor/portable-git/2.55.0/bin:/storage/Users/currentUser/.harmonybrew/bin:$PATH

eval "$(/storage/Users/currentUser/.harmonybrew/bin/brew shellenv)"

重要：每次重新进入容器都需要执行这两条命令设置 PATH。建议使用第 12 步的启动脚本简化操作。

9.2 验证 git 可用

git --version

预期输出：

git version 2.55.0

说明：git 来自 harmonybrew 安装时自动下载的 portable-git，位于 Homebrew 内部 vendor 目录，不在标准 PATH 中，需要手动添加。

9.3 配置 Git 身份

将用户名和邮箱替换为你自己的。如果不确定自己的用户名和邮箱是什么，可以在 AtomGit 上新建一个空项目，创建完成后页面会显示完整的 Git 全局设置命令，其中就包含你的用户名和邮箱：

git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

示例（使用 AtomGit/GitCode 账号）：

git config --global user.name "your_username"
git config --global user.email "your_email@example.com"

9.4 生成 SSH 密钥

ssh-keygen -t ed25519 -C "你的邮箱" -f ~/.ssh/id_ed25519 -N ""

示例：

ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519 -N ""

9.5 查看公钥

cat ~/.ssh/id_ed25519.pub

预期输出（内容因人而异）：

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... your_email@example.com

9.6 添加公钥到 AtomGit

登录 atomgit.com
右上角头像 → 设置 → SSH 公钥
将上一步输出的公钥内容粘贴进去
点击添加

9.7 验证 SSH 连接

ssh -T git@atomgit.com

首次连接会提示是否信任主机，输入 yes：

The authenticity of host 'atomgit.com (116.205.2.91)' can't be established.
RSA key fingerprint is: SHA256:aTlsy+4ARMC7nWyy5eKIqUkotk8yv7Jd+XXoP4EXj1Y
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'atomgit.com' (RSA) to the list of known hosts.
** WARNING: connection is not using a post-quantum key exchange algorithm.
** This session may be vulnerable to "store now, decrypt later" attacks.
** The server may need to be upgraded. See https://openssh.com/pq.html
remote: Welcome to GitCode, your_username

成功标志：最后显示 remote: Welcome to GitCode, 你的用户名。

10. 注册 AtomGit 并 Fork 仓库

操作位置：浏览器（AtomGit 网站）

10.1 注册 AtomGit 账号

如果还没有 AtomGit 账号，去 atomgit.com 注册。

10.2 Fork homebrew-core 仓库

在浏览器打开：https://atomgit.com/harmonybrew/homebrew-core
点击右上角 Fork 按钮
Fork 到你的个人账号下
Fork 完成后，你的仓库地址为：https://atomgit.com/你的用户名/homebrew-core

11. 克隆 Fork 并配置上游仓库

操作位置：DockerHarmony 容器内（# 提示符）

11.1 确保已设置 PATH

export PATH=/storage/Users/currentUser/.harmonybrew/Homebrew/Library/Homebrew/vendor/portable-git/2.55.0/bin:/storage/Users/currentUser/.harmonybrew/bin:$PATH
eval "$(/storage/Users/currentUser/.harmonybrew/bin/brew shellenv)"

11.2 克隆你的 Fork

将 你的用户名 替换为你的 AtomGit 用户名：

git clone git@atomgit.com:你的用户名/homebrew-core.git

示例：

git clone git@atomgit.com:your_username/homebrew-core.git

预期输出：

Cloning into 'homebrew-core'...
** WARNING: connection is not using a post-quantum key exchange algorithm.
** This session may be vulnerable to "store now, decrypt later" attacks.
** The server may need to be upgraded. See https://openssh.com/pq.html
remote: Enumerating objects: 150193, done.
remote: Counting objects: 100% (150193/150193), done.
remote: Compressing objects: 100% (35490/35490), done.
remote: Total 150193 (delta 114486, reused 150193 (delta 114486), pack-reused 0 (from 0)
Receiving objects: 100% (150193/150193), 30.66 MiB | 3.37 MiB/s, done.
Resolving deltas: 100% (114486/114486), done.

11.3 进入仓库目录

cd homebrew-core

11.4 添加上游仓库

git remote add upstream https://atomgit.com/harmonybrew/homebrew-core.git

11.5 同步上游最新代码

git pull upstream main

预期输出：

From https://atomgit.com/harmonybrew/homebrew-core
 * branch                main       -> FETCH_HEAD
 * [new branch]          main       -> upstream/main
Already up to date.

11.6 查看仓库结构

ls Formula/a/ | head -10

预期输出：

aamath.rb
abcm2ps.rb
abcmidi.rb
abduco.rb
abnfgen.rb
abook.rb
abpoa.rb
abseil.rb
access.rb
aces_container.rb

Formula 文件按"首字母/包名.rb"组织，例如 wget 的 formula 在 Formula/w/wget.rb。

12. 创建环境启动脚本

操作位置：DockerHarmony 容器内（# 提示符）

每次进入容器都需要配置 PATH 和环境变量。创建一个启动脚本简化操作：

cat > /setup.sh << 'EOF'
#!/bin/sh
export PATH=/storage/Users/currentUser/.harmonybrew/Homebrew/Library/Homebrew/vendor/portable-git/2.55.0/bin:/storage/Users/currentUser/.harmonybrew/bin:$PATH
eval "$(/storage/Users/currentUser/.harmonybrew/bin/brew shellenv)"
cd ~/homebrew-core
echo "环境就绪：brew $(brew --version | head -1)"
echo "git: $(git --version)"
echo "当前目录: $(pwd)"
echo "可用命令: brew install -s <包名> / brew test <包名> / git checkout -b <分支>"
EOF
chmod +x /setup.sh

以后每次进入容器只需要：

. /setup.sh

预期输出：

环境就绪：brew Homebrew 6.0.6_11
git: git version 2.55.0
当前目录: /root/homebrew-core
可用命令: brew install -s <包名> / brew test <包名> / git checkout -b <分支>

13. 容器内安装 Node.js 和 OpenDesk

操作位置：DockerHarmony 容器内（# 提示符）

在容器内安装 OpenDesk CLI，可以直接在容器中运行 AI Agent，避免手动复制粘贴命令。

13.1 安装 Node.js

brew install node

13.2 验证 Node.js

node --version

预期输出：

v26.7.0

npm --version

预期输出：

11.19.0

13.3 安装 OpenDesk CLI

运行以下命令安装 OpenDesk CLI 的最新日构建版本：

npm i -g "@bitclub.ai/opendesk-cli@nightly"

或安装最新稳定版本：

npm i -g "@bitclub.ai/opendesk-cli@latest"

13.4 启动 OpenDesk

opendesk

启动后按照终端界面提示配置基础模型（LLM API），即可开始使用。

OpenDesk CLI 说明：

OpenDesk CLI 是 OpenDesk 面向开发场景的发行版本

终端界面基于 pi-tui 实现，支持百万词上下文长任务的流式渲染

配置基础模型后即可快速上手

在容器内运行 OpenDesk，可以直接让 AI 在容器环境中执行命令、编写 Formula、提交 PR，无需手动复制粘贴

14. 环境验证清单

完成所有步骤后，执行以下验证：

# 1. 确认在容器内
uname -a
# 预期：Linux ... aarch64 ...

# 2. zsh
zsh --version
# 预期：zsh 5.9 (aarch64-unknown-linux-gnu)

# 3. harmonybrew
brew --version
# 预期：Homebrew 6.0.6_11

# 4. 编译器
which cc gcc clang make
# 预期：都在 /storage/Users/currentUser/.harmonybrew/bin/ 下

clang --version
# 预期：clang version 15.0.4, Target: aarch64-unknown-linux-ohos

make --version
# 预期：GNU Make 4.4.1

# 5. git
git --version
# 预期：git version 2.55.0

# 6. SSH 认证
ssh -T git@atomgit.com
# 预期：remote: Welcome to GitCode, 你的用户名

# 7. 仓库
cd ~/homebrew-core && git remote -v
# 预期：origin 指向你的 fork，upstream 指向 harmonybrew/homebrew-core

# 8. Node.js（如果安装了）
node --version
# 预期：v26.7.0

# 9. OpenDesk（如果安装了）
opendesk --version

15. 日常使用流程

15.1 每次开始工作

# 1. 在融合开发引擎虚拟机终端中启动容器（如果容器未运行）
sudo podman start ohos

# 2. 进入容器
sudo podman exec -it ohos sh

# 3. 在容器内加载环境
. /setup.sh

# 4. 同步上游最新代码
cd ~/homebrew-core
git pull upstream main

15.2 修复已有包

# 1. 创建工作分支
git checkout -b 包名-fix-描述

# 2. 修改 Formula 或添加补丁
# 编辑 Formula/首字母/包名.rb 或 Patches/包名/xxx.patch

# 3. 从源码编译测试
brew install -y -s -v --include-test 包名

# 4. 冒烟测试
brew test 包名

# 5. 提交
git add -A
git commit -m "包名 版本号 (fix 描述)"
git push origin 包名-fix-描述

# 6. 在 AtomGit 网页提交 PR

15.3 新增包（搬运上游 Formula）

# 1. 从上游下载 Formula 文件
curl -o Formula/首字母/包名.rb \
  https://raw.githubusercontent.com/Homebrew/homebrew-core/master/Formula/首字母/包名.rb

# 2. 从源码编译测试
brew install -y -s -v --include-test 包名

# 3. 冒烟测试
brew test 包名

# 4. 提交 PR
git checkout -b 包名-版本-new-formula
git add -A
git commit -m "包名 版本号 (new formula)"
git push origin 包名-版本-new-formula

15.4 PR 规则

一个 PR → 一个 commit → 一个 formula
commit message 格式：包名版本号 (new formula) 或 包名版本号 (fix 描述)
必须是开源软件，源码来自官方仓库
禁止录入预构建二进制文件
英文注释

15.5 依赖管理

如果包 A 依赖包 B，必须先提交包 B 的 PR 并等待合并发布后，再提交包 A 的 PR：

① 包B（底层依赖，无依赖）→ PR → CI 编译测试 → 合并 → 上传 bottle
② 包A（依赖包B）→ PR → CI 从 OBS 下载包B的 bottle → 编译包A → 测试 → 合并 → 上传

15.6 CI 流水线流程

你提交 PR → AtomGit webhook → CI 流水线自动执行：
  ① 门禁检查（PR 规范）
  ② 从源码编译（按 Formula 中的 install 方法）
  ③ brew test（按 Formula 中的 test 方法）
  ④ 打包 bottle
  ⑤ 上传到 OBS
  ⑥ 结果自动发回 PR 讨论区

成功 → 机器人自动合并（10分钟周期）
失败 → 看日志 → 修改 → git push -f → 重新评审

16. 常见问题

16.1 容器内执行命令报 `cannot execute: required file not found`

原因：你在融合开发引擎虚拟机中操作，不在容器内。鸿蒙二进制需要 musl libc，虚拟机使用 glibc，不兼容。

解决：进入容器 sudo podman exec -it ohos sh，确认提示符是 #。

16.2 `brew install` 报文件锁错误

Error: A `brew install` process has already locked ...

原因：之前的 brew 进程被 Ctrl+Z 挂起，锁文件还在。

解决：

kill %1 2>/dev/null
rm -f /root/.cache/Homebrew/downloads/*.incomplete
brew install 包名

16.3 `git` 命令找不到

原因：portable-git 不在默认 PATH 中。

解决：

export PATH=/storage/Users/currentUser/.harmonybrew/Homebrew/Library/Homebrew/vendor/portable-git/2.55.0/bin:/storage/Users/currentUser/.harmonybrew/bin:$PATH
eval "$(/storage/Users/currentUser/.harmonybrew/bin/brew shellenv)"

或使用启动脚本：. /setup.sh

16.4 `ssh-keygen` 命令找不到

原因：容器内默认没有 openssh。

解决：brew install openssh

16.5 SSH 连接 AtomGit 报 `connection is not using a post-quantum key exchange algorithm`

这是警告信息，不影响使用，可以忽略。

16.6 容器重启后环境丢失

容器不会自动重启。如果容器停止了：

# 在融合开发引擎虚拟机终端中
sudo podman start ohos
sudo podman exec -it ohos sh

容器内的文件和安装的软件不会丢失（持久化在 Podman 存储中），但 PATH 等环境变量需要重新设置：

. /setup.sh

16.7 下载 zsh 报 404

原因：URL 拼写错误，releases 被拼成了 realeases（多了个 a）。

正确 URL：

https://github.com/Harmonybrew/ohos-zsh/releases/download/5.9/zsh-5.9-ohos-arm64.tar.gz

附录 A：提交到 harmonybrew 的内容说明

你提交的 PR 内容是纯文本文件，不是编译好的二进制：

你提交的 PR 内容：
├── Formula/w/wget.rb          ← Ruby 配方文件（核心）
├── Patches/w/0001-xxx.patch   ← 补丁文件（如果有的话）
└── Aliases/wget               ← 软链接（如果上游有的话）

Formula 是一份"怎么从源码编译这个软件"的说明书，用 Ruby DSL 编写的纯文本。CI 流水线会按这份说明书自动编译、测试、打包、分发。

你只负责写说明书，CI 负责按说明书编译。用户最终装的是 CI 编译好的 Bottle（预编译包）。

附录 B：Formula 基本结构

class Wget < Formula
  desc "Internet file retriever"                    # 描述
  homepage "https://www.gnu.org/software/wget/"      # 主页
  url "https://ftpmirror.gnu.org/gnu/wget/wget-1.25.0.tar.gz"  # 源码 URL
  sha256 "766e48423e79359ea31e41db9e5c289675947a7fcf2efdcedb726ac9d0da3784"  # 校验值
  license "GPL-3.0-or-later"                        # 许可证

  # 已有鸿蒙预编译包
  bottle do
    sha256 cellar: :any_skip_relocation, arm64_ohos: "39b22..."
  end

  # 依赖声明
  depends_on "pkgconf" => :build    # 编译依赖
  depends_on "openssl@3"           # 运行依赖

  # Linux 平台依赖（鸿蒙走此分支）
  on_linux do
    depends_on "util-linux"
    depends_on "zlib-ng-compat"
  end

  # 编译逻辑
  def install
    system "./configure", "--prefix=#{prefix}", "--with-ssl=openssl"
    system "make", "install"
  end

  # 测试逻辑
  test do
    system bin/"wget", "-O", File::NULL, "https://google.com"
  end
end

附录 C：补丁制作流程

# 1. 下载源码包，解压两次
mkdir a b
tar xzf wget-1.25.0.tar.gz -C a    # 原始
tar xzf wget-1.25.0.tar.gz -C b    # 要修改的

# 2. 在 b 目录中修改源码

# 3. 生成补丁
diff -ruN a/wget-1.25.0 b/wget-1.25.0 > 0001-add-ohos-support.patch

# 4. 放置补丁
mkdir -p Patches/wget
cp 0001-add-ohos-support.patch Patches/wget/

# 5. 在 Formula 中引用补丁
# 在 wget.rb 中添加：
#   patch do
#     url "file://Patches/wget/0001-add-ohos-support.patch"
#     sha256 "def456..."
#   end

# 6. 验证
brew install -y -s -v --include-test wget
brew test wget

参考来源：

Alpine Linux aports（musl libc 兼容性补丁）
Termux packages（Android 沙箱适配实践）

附录 D：参考链接

Harmonybrew 项目

名称	链接	说明
Harmonybrew 组织主页	https://atomgit.com/Harmonybrew	AtomGit 上的组织主页，包含所有仓库
Harmonybrew 文档仓库	https://atomgit.com/Harmonybrew/docs	完整中文文档（安装、贡献、维护、FAQ 等）
homebrew-core 仓库	https://atomgit.com/Harmonybrew/homebrew-core	Formula 配方仓库，提交 PR 的目标仓库
Harmonybrew 项目主页	https://harmonybrew.atomgit.com	项目主页，包含安装脚本和包索引

DockerHarmony 容器

名称	链接	说明
容器安装教程（CSDN）	https://blog.csdn.net/hqzing/article/details/155165753	DockerHarmony 作者 hqzing 的博文，介绍容器化鸿蒙环境
融合开发引擎 Podman 配置笔记	https://my.feishu.cn/wiki/FnmSwU70jihXLtkJ1zKcICeenVc	B 站用户 @零炴分享的飞书笔记，Podman 在融合开发引擎中的配置方法
DockerHarmony GitHub	https://github.com/hqzing/dockerharmony	容器镜像源码和构建说明
DockerHarmony 镜像（GHCR）	`ghcr.io/hqzing/dockerharmony:latest`	Podman 拉取地址
DockerHarmony 镜像（Docker Hub）	`hqzing/dockerharmony:latest`	Docker 拉取地址

鸿蒙移植工具链

名称	链接	说明
ohos-zsh	https://github.com/Harmonybrew/ohos-zsh/releases	鸿蒙版 zsh 下载
ohos-coreutils	https://github.com/Harmonybrew/ohos-coreutils	鸿蒙版 coreutils
ohos-make	https://github.com/Harmonybrew/ohos-make	鸿蒙版 make
ohos-git	https://github.com/Harmonybrew/ohos-git	鸿蒙版 git
ohos-openssh	https://github.com/Harmonybrew/ohos-openssh	鸿蒙版 openssh
ohos-ruby	https://github.com/Harmonybrew/ohos-ruby	鸿蒙版 ruby
ohos-bash	https://github.com/Harmonybrew/ohos-bash	鸿蒙版 bash
ohos-python	https://github.com/Harmonybrew/ohos-python	鸿蒙版 python

完整工具列表见容器安装教程博文的"工具获取"章节。

Homebrew 上游

名称	链接	说明
Homebrew 官网	https://brew.sh	Homebrew 包管理器官网
Formula Cookbook	https://docs.brew.sh/Formula-Cookbook	Homebrew Formula 编写指南
上游 homebrew-core	https://github.com/Homebrew/homebrew-core	上游 Formula 仓库（搬运来源）
Formula 搜索	https://formulae.brew.sh	搜索上游已有的 Formula

OpenDesk

名称	链接	说明
OpenDesk CLI 安装	`npm i -g "@bitclub.ai/opendesk-cli@nightly"`	日构建版本
OpenDesk CLI 安装（稳定）	`npm i -g "@bitclub.ai/opendesk-cli@latest"`	最新稳定版本

补丁参考来源

名称	链接	说明
Alpine Linux aports	https://gitlab.alpinelinux.org/alpine/aports	musl libc 兼容性补丁参考
Termux packages	https://github.com/termux/termux-packages	Android 沙箱适配实践参考

文档版本：v1.1

最后更新：2026-08-14

基于环境：HarmonyOS 6.1 + 融合开发引擎 + Podman + DockerHarmony + Harmonybrew 6.0.6

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

HarmonyOS 鸿蒙 ArkUI 保留属性名踩坑实录 —— 那些「看起来能命名、一编译就报错」的 @Prop

人工智能6S服务平台

HarmonyOS 鸿蒙 CollectibleBookshelf 原生 3D 书架实战 —— 不用 WebGL，一个 rotateY 逼出来的投影布局法

人工智能6S服务平台

鸿蒙掌上驾考宝典应用开发49:鸿蒙推送服务——PushUtils 与通知管理

/ 图片/视频 URL（用于富媒体通知）// 推送标题id: string;// 推送 ID（用于去重和追踪）推送服务是应用与用户保持互动的重要渠道。权限管理：通知权限的申请和检查消息构建：NotificationRequest 的消息结构推送发送：通过 notificationManager.publish 发送点击处理：通过 Want 参数传递，支持冷启动和热启动页面跳转：根据推送类型跳转到不

人工智能6S服务平台

所有评论(0)

查看更多评论

qq_57467750

@qq_57467750

已为社区贡献6条内容

鸿蒙 PC 搭建 Harmonybrew 贡献开发环境指南（融合开发引擎 + DockerHarmony + OpenDesk）

qq_57467750

鸿蒙 PC 搭建 Harmonybrew 贡献开发环境指南（融合开发引擎 + DockerHarmony + OpenDesk）

目录

1. 整体架构

2. 启动融合开发引擎

2.1 什么是融合开发引擎

2.2 启动步骤

3. 在融合开发引擎中安装 Podman

3.1 创建 Podman 配置文件

3.2 安装 Podman

3.3 创建并挂载 cgroup

4. 拉取并运行 DockerHarmony 容器

4.1 拉取镜像

4.2 启动容器

4.3 进入容器

4.4 关于 DockerHarmony 容器

5. 容器内安装 zsh

5.1 下载 zsh

5.2 解压

5.3 创建符号链接

5.4 验证

6. 容器内安装 Harmonybrew

6.1 运行安装脚本

6.2 配置环境变量

6.3 验证

7. 容器内安装开发工具链 devel-base

7.1 安装 devel-base

7.2 验证工具链

8. 容器内安装 openssh

9. 配置 Git 和 SSH 密钥

9.1 设置 PATH

9.2 验证 git 可用

9.3 配置 Git 身份

9.4 生成 SSH 密钥

9.5 查看公钥

9.6 添加公钥到 AtomGit

9.7 验证 SSH 连接

10. 注册 AtomGit 并 Fork 仓库

10.1 注册 AtomGit 账号

10.2 Fork homebrew-core 仓库

11. 克隆 Fork 并配置上游仓库

11.1 确保已设置 PATH

11.2 克隆你的 Fork

11.3 进入仓库目录

11.4 添加上游仓库

11.5 同步上游最新代码

11.6 查看仓库结构

12. 创建环境启动脚本

13. 容器内安装 Node.js 和 OpenDesk

13.1 安装 Node.js

13.2 验证 Node.js

13.3 安装 OpenDesk CLI

13.4 启动 OpenDesk

14. 环境验证清单

15. 日常使用流程

15.1 每次开始工作

15.2 修复已有包

15.3 新增包（搬运上游 Formula）

15.4 PR 规则

15.5 依赖管理

15.6 CI 流水线流程

16. 常见问题

16.1 容器内执行命令报 cannot execute: required file not found

16.2 brew install 报文件锁错误

16.3 git 命令找不到

16.4 ssh-keygen 命令找不到

16.5 SSH 连接 AtomGit 报 connection is not using a post-quantum key exchange algorithm

16.6 容器重启后环境丢失

16.7 下载 zsh 报 404

附录 A：提交到 harmonybrew 的内容说明

附录 B：Formula 基本结构

附录 C：补丁制作流程

附录 D：参考链接

Harmonybrew 项目

DockerHarmony 容器

鸿蒙移植工具链

Homebrew 上游

OpenDesk

补丁参考来源

16.1 容器内执行命令报 `cannot execute: required file not found`

16.2 `brew install` 报文件锁错误

16.3 `git` 命令找不到

16.4 `ssh-keygen` 命令找不到

16.5 SSH 连接 AtomGit 报 `connection is not using a post-quantum key exchange algorithm`