开源鸿蒙PC三方库学习：在鸿蒙PC上用 vcpkg 管理 C++ 三方库，从环境搭建到第一个库安装

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

开源仓库地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_vcpkg

2026 年 4 月，Qt 官方给 vcpkg 提交了 HarmonyOS 支持，这意味着微软这个 C++ 包管理器从此可以识别 ohos 平台、为鸿蒙交叉编译三方库了。对开发者来说，这意味着用一条命令就能装库，不用再手写交叉编译脚本。

本篇基于社区作者 特立独行的猫a 的《使用 vcpkg 为鸿蒙下载与安装三方库实践指南》整理，结合我自己的搭建过程重新讲述。

前置认知：vcpkg 是什么

如果你之前主要用 CMake + apt 或 homebrew 管理 C/C++ 依赖，vcpkg 可以理解成一个「和你项目紧密结合的包管理器」——它不光下载库，还为你的目标平台交叉编译、把产物放到统一前缀下，CMake 项目通过 toolchain file 就能直接 find_package 到它管的所有库。

它与 CMake 的深度集成是最大卖点：不需要手动设 -I、-L、-l，只要在 CMake 参数里加一行 -DCMAKE_TOOLCHAIN_FILE=…/vcpkg.cmake，所有安装过的库就会被 CMake 自动发现。

Qt 团队维护的 fork 在此基础上做了两件事：一是在 vcpkg-tool 里让构建工具能识别 ohos 平台；二是在 registry 里提供三组 triplet（arm64-ohos、arm-ohos、x64-ohos）和针对 OHOS 的 portfile 补丁。这两个仓库的地址是：

# registry（port目录，包含具体的库构建脚本和补丁）
git clone https://gitcode.com/OpenHarmonyPCDeveloper/ohos_vcpkg
# 或者 Qt 原版 registry
git clone https://git.qt.io/jobor/vcpkg

为什么 vcpkg 对鸿蒙原生 C/C++ 开发有意义

在没有 vcpkg 之前，鸿蒙模式下用 C/C++ 三方库，典型流程是：找到库的源码 → 自己配置交叉编译工具链 → 处理 musl / 平台差异 → 逐个解决编译错误 → 手动把产物拷到工程里。这个流程的问题不是「能不能」，而是「每次都要手工一遍」——换个库就重来，换个版本也重来，而且编译过程中的踩坑经验不容易复用。

vcpkg 解决的就是这个问题：把「怎么编」的知识固化在 portfile 里。一次写好后，任何人执行 vcpkg install 库名:arm64-ohos 就能得到目标产物，不需要知道这个库的 Makefile 有什么特殊开关、musl 兼容要改哪几行代码——portfile 已经帮你搞定了。

更深远的意义在于：Qt 团队的行动直接推动了鸿蒙进入全球 C++ 包管理生态。微软主分支已接受相关 PR（#51470），这意味着未来任何支持 vcpkg 的开源 C/C++ 项目，理论上都可以「顺手」支持鸿蒙。

环境搭建：三大件缺一不可

我在 WSL Ubuntu 上搭了这套环境，需要准备三样东西：

1. HarmonyOS SDK（API 12+）

这是交叉编译的根基。SDK 里的 native/llvm/bin/ 提供了 aarch64-linux-ohos-clang、clang++ 等编译工具，以及 native/sysroot/ 下的头文件和系统库。最关键的环境变量是 OHOS_SDK_ROOT：

export OHOS_SDK_ROOT=/path/to/ohos-sdk/linux
# 快速验证 clang++ 是否存在
ls "$OHOS_SDK_ROOT/native/llvm/bin/clang++"

这个环境变量是 vcpkg triplet 文件里读取 OHOS SDK 路径的依据，少设、设错都会让 vcpkg 在编译阶段报找不到 sysroot。

2. CMake 3.20+ 和 Ninja

vcpkg 依赖 CMake 来配置构建，Ninja 作为默认构建后端：

sudo apt-get install -y cmake ninja-build
cmake --version   # 确认 ≥ 3.20
ninja --version

3. vcpkg 本体和 registry

# clone vcpkg 主仓库
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh    # 编译出 vcpkg 命令行工具

# registry 可以 clone 到本地，也可以让 vcpkg 从 git remote 读取

小提醒：初次 bootstrap 时 vcpkg 会从网络下载一个预编译的 vcpkg-tool 二进制，国内网络可能很慢，建议配置好代理或提前下载好 tool 放入 downloads/ 目录。另外确认 zip 命令已安装（apt install zip），有些 port 解压会用到它。

第一个库：安装 curl 并验证

环境就绪后，用 curl 来跑通第一个安装流程——curl 依赖少、编译快，是最合适的验证目标：

vcpkg install curl:arm64-ohos

这条命令里 :arm64-ohos 就是 triplet，告诉 vcpkg 我要给 arm64 的 ohos 平台编译。vcpkg 会自动完成以下步骤：

1. 解析 curl 的 vcpkg.json，识别依赖（zlib、openssl 等）；
2. 按拓扑顺序先编译依赖库；
3. 用传入的 triplet 交叉编译工具链编译每个库；
4. 把产物安装到 installed/arm64-ohos/ 目录下。

装好后看一眼产物结构：

tree installed/arm64-ohos/ -L 2
# installed/arm64-ohos/
# ├── bin/          ← 可执行文件
# ├── include/      ← 头文件
# ├── lib/          ← .so 动态库
# ├── share/        ← cmake 包配置、版权声明
# └── debug/        ← debug 版本的库

share/ 目录里自动生成了 CMake 包配置文件，这意味着在你的 CMake 项目里只需加一行 find_package(CURL REQUIRED) 就能链上这个鸿蒙版 curl。

真机验证两步走

第一步，CMake 集成验证：写一个最简单的 CMake 项目，用 curl 调个 HTTP 请求：

cmake_minimum_required(VERSION 3.20)
project(curl_test)
find_package(CURL REQUIRED)
add_executable(curl_test main.cpp)
target_link_libraries(curl_test PRIVATE CURL::libcurl)

构建时指定 vcpkg 的 toolchain file：

cmake -B build \
  -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake \
  -DVCPKG_TARGET_TRIPLET=arm64-ohos
cmake --build build

第二步，真机运行：把产物和 runtime so 拷到设备上，签名后执行。鸿蒙上需要 binary-sign-tool 签名：

binary-sign-tool sign -inFile app -outFile app -selfSign "1"
chmod +x app
./app

常见踩坑

现象	根因	应对
install 时下载源码缓慢	GitHub 访问慢	配置镜像代理，或手动下载放 downloads/
Could not find OHOS SDK	OHOS_SDK_ROOT 未设或路径错	检查环境变量，确认指向 SDK 根目录
openssl 编译报错	openssl 的 port 需要额外补丁	检查 vcpkg registry 是否包含对应版本的修复
zip: not found	系统未安装 zip	apt install zip

小结

vcpkg 进入鸿蒙生态，本质上是把「手工交叉编译」变成了「声明式依赖管理」。对 Qt 开发者来说这是无缝衔接，对普通 C/C++ 开发者来说则提供了一条更「国际通用」的鸿蒙三方库获取路径。下一篇我会把它和另一套方案 lycium_plusplus 做个对比，看看两条路各自的适用场景。

感谢原创作者 特立独行的猫a 的开源分享。