OpenHarmony 鸿蒙 PC + CodeArts IDE 实现 Rust开发完整开发环境搭建指南

本文讲解鸿蒙 PC 端 Rust 开发环境搭建，鸿蒙基于 musl 库、强制二进制签名，无法直接使用通用 Linux 编译产物。需借助鸿蒙专属包管理器 Harmonybrew，提供两套编译方案：方案一安装 llvm-gcc-compat，零配置开箱即用；方案二仅安装 ohos-sdk，需手动配置 Cargo 链接器，二者都依托 ohos-sdk 完成自动签名编译。

欢迎加入开源鸿蒙PC社区： https://harmonypc.csdn.net/

欢迎在PC社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

AtomGit 仓库地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_rust_cargo

---

前言：

OpenHarmony（鸿蒙 PC / 标准系统）基于 Linux 内核，但做了大量定制改造、权限管控与运行环境隔离，和通用 Linux 发行版并非完全兼容，这就让普通 Rust 编译出来是 glibc 版本不能运行。

• 不用 glibc（Ubuntu/Windows 用的），鸿蒙用 musl 轻量级 C 库
• 用 musl libc（轻量、嵌入式、鸿蒙专用），普通 Rust 编译（x86_64-unknown-linux-gnu）是glibc，直接运行必崩
• 编译器不是 gcc，是 OHOS 定制 Clang/LLVM，鸿蒙没有原生 Rust 编译器，只支持交叉编译
• 链接器是 lld（LLVM 链接器），不是 ld，Rust 必须用 aarch64-unknown-linux-ohos 专属目标（musl ABI）
• 所有二进制必须 签名 才能在鸿蒙 PC / 设备运行

以上的原因会造成鸿蒙机器不能直接运行原生 Rust 环境，核心是：鸿蒙内核 + musl + 签名 + 沙箱 + 无原生 rustc，和 Linux/glibc 生态完全割裂，只能交叉编译后跑成品二进制。

鸿蒙（OpenHarmony）不是标准 Linux，是微内核 + musl libc，而 Rust 默认编译是glibc（Ubuntu/PC），两者 ABI、系统调用、库完全不兼容，普通 Rust 程序一跑就闪退、段错误。鸿蒙没有 glibc，只有musl 轻量 C 库，Rust 必须编译成ohos-musl 专属版本，本机做不了。

---

一、什么是Harmonybrew 呢？

鸿蒙不自带 C/C++ 编译环境，且官方不提供鸿蒙版二进制包，所以这些库不能直接用，但它们支持自动编译，我们用 Harmonybrew 提供编译能力，就能让这些库在鸿蒙上自己编译自己，从而正常运行。

相信大多数人都用过 Mac系统，Homebrew 是 macOS / Linux 平台下最主流、最流行的开源命令行包管理器，圈内直接叫 brew。我们可以简单的来类比理解：

• Windows：应用商店、360 软件管家、Chocolatey
• Android：应用商店
• Linux：apt / yum / dnf
• macOS 专属标配：Homebrew

那么，Harmonybrew 是给 OpenHarmony/鸿蒙系统做的「Homebrew 移植版」，本质是一个命令行包管理器，目标是把 macOS/Linux 上最流行的 Homebrew 生态，完整搬到鸿蒙设备上（移植到了 OpenHarmony 操作系统上），这意味着，开发者可以在鸿蒙设备上使用熟悉的 brew install、brew search、brew update 等命令来安装和管理软件包。类似于Ubuntu上的apt-get或CentOS上的yum包管理工具，功能类似于Homebrew（Homebrew是Mac上最好用的包管理工具）。‌‌目前仅只支持 arm64（适配 ARM64 架构）的鸿蒙设备：

• 命令语法、使用逻辑 几乎完全对齐 brew。
• 目标：让鸿蒙设备也拥有类似 Mac 的命令行软件管理能力。

概念	理解
Homebrew	Mac/Linux 下常用的软件安装工具，用 brew install 一键装软件、自动解决依赖。原生版，Mac/Linux 主流包管理器（鼻祖）
Harmonybrew	就是鸿蒙版 Homebrew，让你在鸿蒙 PC、开发板、容器里，也能用同样的 brew 命令装各种命令行工具和开发软件，社区基于 Homebrew 思路移植到 OpenHarmony / 鸿蒙 的版本

Homebrew(Mac) → 设计思想被借鉴 → 衍生出 Harmonybrew(鸿蒙)

---

1.1 为什么需要 Harmonybrew？解决什么痛点？

原生鸿蒙（OpenHarmony）命令行环境极度精简，缺很多常用工具：

• 没有 apt/yum/brew 这种统一包管理器；
• 装 curl、wget、git、python、node、redis 等，只能：
  • 手动下源码 → 编译 → 配环境变量 → 软链接；
  • 依赖经常缺、编译报错、版本混乱、无法一键更新；
• 鸿蒙 PC、开发板、容器之间环境不一致，迁移麻烦。

那么，原生 OpenHarmony 的命令行环境功能比较精简，缺少大量常用开发工具，软件安装、依赖处理都只能手动操作，流程繁琐又容易出错，而 Harmonybrew 的出现，恰好补齐了这一短板：

• 一条命令安装、卸载、更新；
• 自动处理依赖；
• 统一软件仓库，版本可控；
• 尽量兼容 Homebrew 现有包（目前约 60% 可直接用）。

能力	原生 OpenHarmony	Harmonybrew
安装软件	手动编译/解压/配路径	brew install 一键搞定
依赖管理	手动找依赖、容易冲突	自动解析、安装依赖
版本管理	无统一机制，易混乱	可指定版本、一键升级
编译适配	常因平台/签名报错	内置适配工具，开箱即用
生态规模	极小（只有基础工具）	2000+ 包，接近 Homebrew

---

1.2 环境要求：

• 设备：鸿蒙 PC
• 系统：HarmonyOS 6.1+ / OpenHarmony 6.1+
• 架构：arm64

在使用之前需要开启一下"开发者选项"，我们可以找到"XXX的MateBookPro"左侧选项框中，在"关于本机"中，我们找到"软件版本"这里，连点 7 次鼠标，即可开启"开发者选项"，如下图所示：

后面我们通过重启电脑即可启用"开发者选项"。

接下来，我们在"隐私与安全"选项中，将"运行来自非应用市场的扩展程序"，将它开启即可。

---

1.3 卸载冲突软件：

如果 PC 中安装有 GitNext 和 DevBox 这两个应用，请先将它们卸载，这些应用可能与 Homebrew 的运行环境产生冲突。

---

1.4 安装命令（一行搞定） - 执行一键安装命令：

接着打开鸿蒙PC自带的终端，千万不要安装HiSH软件，一直提示我安装错误。

下面是 Harmonybrew（鸿蒙版 Homebrew）官方一键安装 Shell 脚本，也是鸿蒙设备部署 Harmonybrew 包管理器的唯一官方入口，基于标准 Homebrew 安装脚本深度适配 OpenHarmony/HarmonyOS 系统，全程自动化完成环境检测、依赖校验、程序下载、目录部署与基础配置，无需人工干预复杂操作，脚本会下载 Harmonybrew 本体，并且配置 PATH，自动修复常见环境问题。

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

• 1.一键部署 Harmonybrew：
  • 替代手动下载、编译、配置等繁琐操作，在鸿蒙 PC、OpenHarmony 开发板、鸿蒙容器中自动安装包管理器核心程序，让鸿蒙设备拥有类似 macOS/Linux 的 brew 软件管理能力。
• 2.系统环境强校验：
  • 提前检测系统类型、架构、Shell 环境、依赖工具，拦截不兼容环境、非法权限、冲突配置，避免安装失败。
• 3.鸿蒙系统专属适配：
  • 针对鸿蒙 /system 目录只读、musl 库、权限机制、服务逻辑等特性做定制改造，解决原生 Homebrew 无法在鸿蒙运行的问题。
• 4.目录与环境自动配置：
  • 自动创建专属安装目录、缓存目录，创建软链接，并在安装结束后给出环境变量配置指引，保证 brew 命令全局可调用。
• 5.多模式兼容：
  • 支持交互式（日常手动安装）、非交互式（CI / 自动化脚本）、CI 环境等运行模式，适配个人使用与自动化部署场景。

---

1.5 配置环境变量：

把 Harmonybrew 的环境初始化代码 写入你的终端配置文件 .zshrc，以后每次打开终端，都会自动加载 brew 命令，不用每次手动配置，总结就是把 Harmonybrew 配置进你的终端环境，让你每次打开 HiShell 都能直接使用 brew 命令，并且当前终端立即生效。

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

---

二、如何编译 Rust 程序？

这里有两种方案来实现编译Rust程序，两种方案最终效果一致：编译出带代码签名、可直接在鸿蒙 PC 运行的 Rust 二进制，底层均依赖 OpenHarmony SDK 的 clang + 封装版 ld.lld 完成链接签名，核心差异在于是否自动适配系统默认 cc 命令、是否需要手动配置 Cargo，适用场景不同。

2.1 方案特点描述：

方案1：安装llvm-gcc-compat（推荐懒人/通用场景） => 【简单省事、快速上手】：

• 1. 依赖联动：安装llvm-gcc-compat会自动拉取 ohos-sdk，无需单独安装SDK。
• 2. 零配置：利用系统软链接让默认cc指向鸿蒙SDK的clang，不用修改任何 Cargo 配置文件。
• 3. 流程最简：一条 brew 命令装好环境，直接 cargo build 即可编译运行。
• 4. 适配性：全局生效，所有Rust项目默认走鸿蒙链接器，适合多项目、临时开发。

方案2：仅安装 ohos-sdk（推荐精细化/隔离场景） => 【多套编译工具链、需要环境隔离】：

• 1. 依赖独立：只安装鸿蒙SDK，不额外装兼容层工具。
• 2. 需手动配置：必须在用户级 ~/.cargo/config.toml 中手动指定 linker/ar 路径，否则编译不生效。
• 3. 环境隔离：不会改动系统默认 cc 指向，原有编译环境不受影响。
• 4. 适配性：配置全局生效，也可按项目单独配置，适合需要区分多套编译链的场景。

对比项	方案1：安装 llvm-gcc-compat	方案2：仅安装 ohos-sdk
所需安装包	rust + llvm-gcc-compat（自动依赖 ohos-sdk）	rust + ohos-sdk
Cargo 配置	无需任何配置	必须手动编写 ~/.cargo/config.toml
系统 cc 软链接	自动指向鸿蒙 clang 驱动器	不改动系统原有 cc
环境侵入性	较高，全局替换默认编译链接器	低，仅Cargo层面指定链接器
操作步骤	少，开箱即用	多，多一步配置文件编写
适用场景	快速开发、多项目通用、不想维护配置	多编译链共存、环境隔离、精细化管控
底层链接逻辑	clang 调用封装 ld.lld，自动签名	同左，最终产物效果一致

---

2.2 【方案二】：不安装 llvm-gcc-compat，仅安装 ohos-sdk：

ohos-sdk 是 OpenHarmony SDK（开源鸿蒙软件开发工具包），场景里特指鸿蒙 PC/OpenHarmony PC 的交叉编译工具链 + 系统库 + 签名工具，是给 Rust/C/C++ 编译出鸿蒙 PC 可运行、带签名二进制的核心工具，ohos-sdk 就是鸿蒙 PC 专用的编译器 + 链接器 + 系统库 + 签名工具合集，让你在 Mac/Linux 上编译出aarch64-unknown-linux-ohos架构、自带代码签名、可直接在鸿蒙 PC 运行的 Rust/C/C++ 程序。

• 完整安装 Rust 编程语言的整套运行与编译环境，包含 rustc 编译器、cargo 工程管理工具、Rust 标准库、目标平台编译支持等核心组件，安装完成后你就可以正常创建 Rust 项目、编写代码并执行编译、运行、打包等常规操作，这也是后续开发代码的基础环境。
• 开源鸿蒙原生开发工具包，结合你编译鸿蒙 PC 端程序的场景，这个包安装后会在本地预设目录（~/.harmonybrew/opt/ohos-sdk/）部署一整套鸿蒙专用原生编译工具链，里面包含基于 LLVM 的 clang 编译器、定制化的 ld.lld 链接器、llvm-ar 归档工具、鸿蒙系统运行库以及内置的代码签名相关脚本与工具。

# 仅安装 rust 和 ohos-sdk，不安装 llvm-gcc-compat
brew install rust ohos-sdk

这套工具链是专门针对鸿蒙 PC 的 aarch64 架构做适配的，尤其是经过二次封装的 ld.lld，在链接阶段会自动为二进制程序添加鸿蒙系统认可的代码签名，这也是编译产物能直接在鸿蒙 PC 设备上运行的核心原因。

只安装了 Rust 环境和鸿蒙 SDK 本体，不会自动安装 llvm-gcc-compat 兼容层。而默认情况下，rustc 在完成代码编译后，会调用系统默认的 cc 命令来完成链接环节，当前系统里的 cc 并没有被软链接指向 ohos-sdk 中的 clang 工具，依然沿用系统原本的编译链接程序。这就导致如果不做任何额外配置，Rust 编译时会使用系统原生工具链，编译出的程序架构、签名、系统库都不符合鸿蒙 PC 的运行要求，无法正常运行。

~/.harmonybrew/opt/ohos-sdk/
└── native/
    ├── llvm/
    │   └── bin/
    │       ├── clang        # 编译器
    │       ├── ld.lld       # 链接器（封装签名）
    │       ├── llvm-ar      # 打包
    │       └── ...
    ├── lib/                  # 鸿蒙系统库
    └── binary-sign-tool      # 签名工具

---

2.3 通过 config.toml 来配置 linker 路径：

.cargo 是 Cargo 工具默认的全局配置目录，所有针对当前用户的 Cargo 通用配置、编译链设置、镜像源、目标平台参数都会存放在这个目录里，只有目录存在，后续的配置文件才能正常生效。

# 编写一个用户级的 config.toml
mkdir -p ~/.cargo/
cat > ~/.cargo/config.toml << 'EOF'
[target.aarch64-unknown-linux-ohos]
ar = "/storage/Users/currentUser/.harmonybrew/opt/ohos-sdk/native/llvm/bin/llvm-ar"
linker = "/storage/Users/currentUser/.harmonybrew/opt/ohos-sdk/native/llvm/bin/clang"
EOF

这是 Cargo 专属的配置文件，采用 TOML 格式，专门用来定制编译行为。第一行 [target.aarch64-unknown-linux-ohos] 是配置的目标平台分组，aarch64-unknown-linux-ohos 是 Rust 为鸿蒙 PC 系统定义的标准目标三元组，代表编译目标为 ARM64 架构、适配 OpenHarmony 系统，写这一行就意味着下方两条配置规则仅对这个鸿蒙目标平台生效，编译其他平台的程序时不会受到影响。

这一整套操作就是先准备好 Cargo 的全局配置目录，再写入针对性的平台规则，手动把鸿蒙 SDK 里的归档工具、链接器和鸿蒙目标平台绑定。因为此前提只安装了 rust 和 ohos-sdk、没有安装 llvm-gcc-compat 兼容层，系统默认的 cc 指令并没有指向鸿蒙工具链，就只能通过这份用户级全局配置，强制 Cargo 在编译鸿蒙架构程序时，全程使用 ohos-sdk 提供的专用工具，补齐工具链调用的关联关系。

---

2.4 创建cargo 工程：

通过命令行快速创建、初始化一个全新的 Rust 项目，同时替换掉默认代码，全程不用手动打开文本编辑器操作文件。

# 创建一个简单的 cargo 工程并将其编译成二进制
cargo new hello_project
cd hello_project
cat > src/main.rs << 'EOF'
fn main() {
    println!("Hello, world!");
}
EOF

先执行 cargo new hello_project，这是 Cargo 工程管理工具的新建项目指令，会在当前目录下自动生成一个名为 hello_project 的标准 Rust 项目目录，同时搭建好完整的项目骨架，包含源码文件夹、项目配置文件以及基础代码模板，目录结构和编译所需的基础文件都会一次性生成完毕。

文件里的内容就是一段最简的 Rust 入口代码，fn main() 是 Rust 程序固定的主函数，也是程序运行的起始入口，函数内部的 println!(“Hello, world!”); 是打印语句，程序运行后就会在终端输出对应的文字。这一步相当于直接覆盖了 cargo new 自动生成的默认示例代码，改成了我们需要的简单测试代码，完成代码部分的初始化，至此整个可编译运行的简易 Rust 项目就准备完成了，接下来执行编译命令就能生成对应二进制程序。

---

2.5 编译并运行：

调用 Cargo 编译当前 Rust 项目并生成正式发布版本的二进制程序，和默认的调试版本不同，加上–release参数后编译器会开启全量代码优化、精简程序体积、剔除调试信息，产出运行效率更高、体积更小的可执行文件，结合此前配置的鸿蒙工具链，编译过程会自动调用指定的 clang 与 llvm-ar，经由封装的链接器完成签名，最终生成适配鸿蒙 PC 架构的程序文件，编译完成后所有产物都会统一存放在项目目录下的target/release文件夹中。

cargo build --release

# 测试编译产物是否能正常运行
./target/release/hello_project

在当前终端直接运行刚刚编译好的程序，顺着层级找到 release 目录下名为hello_project的可执行文件并启动它，因为编译阶段已经完成鸿蒙要求的代码签名，这个程序可以直接在鸿蒙 PC 环境中正常执行，运行后就会输出代码里设定的文本内容，以此验证整个编译、链接、签名流程都正常生效。

---

三、如何使用CodeArts IDE实现【方案一】llvm-gcc-compat提供 cc 命令供 rustc 使用：

这里为了区分与上面不同的编译环境，这里将 llvm-gcc-compat 模块安装在虚拟环境里，并使用虚拟环境里的 Python 运行 rustc 编译器，生成签名后的可执行文件。

接下来我们可以打开CodeArts IDE，点击新建工程，创建一个新的项目。

3.1 安装python虚拟环境：

不同项目可能需要不同版本的 Python、不同版本的依赖库，全局环境混用容易出现版本冲突、库混乱的问题。

虚拟环境模块，就是 Python 自带、不用额外安装的一套工具，用来给不同项目搭 “独立隔离的运行空间”，会复制一份当前 Python 解释器、pip 工具和基础运行文件，打造出一个副本环境，这个副本和系统全局 Python 互不干涉，在里面安装的第三方库、版本配置，都只存在于这个文件夹内，不会影响系统或其他项目。

# 激活 venv
python3 -m venv .venv
source .venv/bin/activate

调用 Python 内置的虚拟环境模块，在当前文件夹里新建一个名为 .venv 的独立虚拟环境文件夹。这个环境会复制一份独立的 Python 解释器、pip，和系统全局 Python 完全隔离，不同项目的依赖不会互相干扰，在这个内置虚拟环境里配合 ohos-pip-autosign，安装的 C 扩展库还能自动签名，完美适配系统安全规则。

当执行虚拟环境里的激活脚本，切换当前终端到这个虚拟环境，激活后终端提示符一般会多出 (.venv) 标识，此时再用 python、pip 命令，就只会作用在这个独立环境里，而非系统全局。

---

3.2 安装 llvm-gcc-compat：

鸿蒙系统（OpenHarmony）的 CodeArts IDE 里，用的是 harmonybrew（适配鸿蒙生态的 Homebrew）来安装 rust 和 llvm-gcc-compat，目标是搭建能直接编译鸿蒙 PC 可运行 Rust 程序的环境。

llvm-gcc-compat 是基于 LLVM 实现的一套 GCC 风格兼容适配工具包，核心作用是抹平系统默认编译指令和鸿蒙 SDK 工具链之间的调用差异，它内部做了软链接与命令行转发处理，会把系统里标准的 cc、gcc 这类通用编译命令，自动指向 ohos-sdk 中搭载的 clang 编译器。

# 安装 rust 和 llvm-gcc-compat（ohos-sdk 会作为 llvm-gcc-compat 的级联依赖被自动引入）
brew install rust llvm-gcc-compat

在 Rust 编译流程里，rustc 编译完成代码后会默认调用系统 cc 作为链接入口，正常情况下这个指令会指向系统原生编译工具，而安装 llvm-gcc-compat 之后，无需手动修改任何 Cargo 配置文件，系统层面的 cc 就会被定向到鸿蒙定制的 clang，进而沿用 clang 配套的封装版 ld.lld 链接器，自动完成二进制文件的代码签名，让最终产物适配鸿蒙 PC 系统运行要求。

省去了手动编写和维护 Cargo 全局配置的步骤，让整套鸿蒙 Rust 编译环境做到开箱即用，所有依赖默认 cc 指令的编译流程，都会无缝切换到鸿蒙官方工具链，全程不需要人为干预工具链路径，同时它保留了传统 GCC 的命令行使用习惯，原有基于 gcc、cc 编写的构建脚本也能直接正常运行。

---

3.3 创建一个cargo 工程：

Cargo 提供的项目初始化命令，它会在当前终端所在的目录下，自动生成一个名为 hello_project 的标准 Rust 项目骨架。这个骨架里会自动创建好项目配置文件 Cargo.toml、源码目录 src，以及一个自带的基础示例代码文件 src/main.rs，帮你省去手动创建目录和文件的麻烦，同时按照 Rust 的规范搭建好项目结构。

# 创建一个简单的 cargo 工程并将其编译成二进制
cargo new hello_project
cd hello_project
cat > src/main.rs << 'EOF'
fn main() {
    println!("Hello, world!");
}
EOF

fn main() 是 Rust 程序的固定入口主函数，程序运行时会从这里开始执行；函数里的 println!(“Hello, world!”); 是 Rust 的标准输出语句，作用是在终端里打印出 Hello, world! 这段文字。这一步会直接覆盖掉 cargo new 自动生成的示例代码，把项目改成一个最简单的测试程序，完成后你就可以直接用 cargo build 命令编译这个项目，生成可执行文件了。

---

3.4 编译并运行：

cargo build --release 是调用 Cargo 工具编译当前项目，并生成发布版（Release）二进制文件，编译完成后，所有发布版产物都会存放在项目目录下的target/release文件夹里，其中就有和项目同名的可执行文件hello_project。

cargo build --release

# 测试编译产物是否能正常运行
./target/release/hello_project

直接在终端里运行刚才编译好的程序，因为前面的编译已经自动完成了鸿蒙签名，这个程序不需要额外处理就能直接在鸿蒙环境里运行，启动后会执行main.rs里的代码，在终端打印出Hello, world!，以此验证整个从项目创建、编译到签名运行的流程都完全正常。

---

四、总结：

本文围绕鸿蒙 PC（OpenHarmony arm64） 搭建 Rust 编译环境展开，核心前提是鸿蒙并非标准 Linux，采用 musl C 库、定制 Clang/LLVM 工具链，且所有可执行文件必须签名才能运行，原生 Rust、通用 Linux 编译产物无法直接使用，需依托鸿蒙专属工具链做交叉编译。

方案一：安装rust + llvm-gcc-compat（推荐快速开发、多项目使用）

通过Harmonybrew一键安装两个包，ohos-sdk会作为依赖自动安装。依靠llvm-gcc-compat自动改写系统cc指向，无需修改任何Cargo配置文件，开箱即用，操作步骤少，但会全局替换系统默认编译工具，环境侵入性相对更高。整体流程：安装软件包 → 创建Cargo项目 → 编写测试代码 → cargo build --release编译 → 直接运行产物。

方案二：仅安装rust + ohos-sdk（推荐多工具链共存、环境隔离场景）

只安装Rust运行环境和鸿蒙SDK本体，不改动系统默认cc指令，环境隔离性强。但必须手动创建并编辑~/.cargo/config.toml，指定鸿蒙SDK内llvm-ar、clang的路径，强制Cargo编译aarch64-unknown-linux-ohos平台时使用专属工具链。后续项目创建、编码、编译、运行流程和方案一一致，仅多了一步配置文件操作。

两套方案下，项目操作逻辑完全相同：终端执行cargo new创建Rust项目，进入项目目录后替换默认源码为测试代码，执行cargo build --release生成开启代码优化的正式版二进制文件，产物存放于target/release目录，最后直接运行该可执行文件，验证编译、签名、运行全流程是否正常。ohos-sdk = 鸿蒙PC编译+链接+签名全套工具，没有它，Rust编译出来的程序不能在鸿蒙PC运行（无签名/架构不对）；而llvm-gcc-compat只是让你不用手动配路径。