HarmonyOS 鸿蒙 PC 平台三方库移植：使用 vcpkg 移植 Crashpad 实战总结
随着 HarmonyOS PC 平台生态逐渐完善，越来越多开发者开始将现有 Linux、Windows 项目迁移至鸿蒙 PC。对于大型应用而言，崩溃捕获与异常上报是不可或缺的基础能力，而 Google 开源的 Crashpad 是目前跨平台崩溃收集方案中的主流选择之一。
本文结合实际项目经验，详细介绍如何通过 vcpkg + CMake 的方式，在 HarmonyOS PC 平台完成 Crashpad 的移植与集成。
一、什么是 Crashpad？
Crashpad 是 Google 开源的跨平台崩溃报告系统。
最初应用于：
- Google Chrome
- Chromium
- Electron
主要功能：
- 捕获程序崩溃
- 生成 Minidump
- 收集异常信息
- 自动上传崩溃报告
- 支持跨平台
支持平台：
| 平台 | 支持情况 |
|---|---|
| Windows | √ |
| Linux | √ |
| macOS | √ |
| Android | √ |
| HarmonyOS PC | 需移植 |
二、为什么选择 vcpkg？
传统移植的问题
手动编译 Crashpad 时：
下载源码
↓
处理依赖
↓
修改编译脚本
↓
适配平台
↓
编译
↓
安装
涉及：
- zlib
- mini_chromium
- gn
- ninja
维护成本较高。
vcpkg 的优势
vcpkg 是微软推出的 C++ 包管理器。
特点：
- 自动管理依赖
- 统一编译参数
- 支持交叉编译
- 与 CMake 深度集成
- 可自定义 Triplet
例如：
vcpkg install crashpad
即可自动拉取相关依赖。
三、HarmonyOS PC 开发环境
环境版本
测试环境：
| 组件 | 版本 |
|---|---|
| HarmonyOS SDK | 6.0 |
| DevEco Studio | 6.0 |
| CMake | 3.28+ |
| Ninja | 1.12+ |
| Clang | HarmonyOS Toolchain |
| vcpkg | 最新版 |
获取 vcpkg
官方仓库：
克隆：
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
初始化：
./bootstrap-vcpkg.sh
Linux：
./vcpkg version
验证安装成功。
四、HarmonyOS 自定义 Triplet
由于官方尚未提供 HarmonyOS PC Triplet，需要自行创建。
目录：
vcpkg/triplets/community
创建：
arm64-harmonyos.cmake
内容示例：
set(VCPKG_TARGET_ARCHITECTURE arm64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)
set(VCPKG_CMAKE_SYSTEM_NAME OHOS)
set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE
/opt/harmony/native/build/cmake/ohos.toolchain.cmake)
set(VCPKG_BUILD_TYPE release)
如果是 x86_64：
x64-harmonyos.cmake
五、移植 Crashpad 过程
查看 Crashpad Port
搜索：
vcpkg search crashpad
输出：
crashpad
查看：
vcpkg info crashpad
首次编译问题
直接执行：
vcpkg install crashpad:arm64-harmonyos
可能出现：
Unsupported platform
原因：
Crashpad Port 中平台判断：
if(WIN32)
elseif(APPLE)
elseif(LINUX)
else()
message(FATAL_ERROR)
endif()
HarmonyOS 无法识别。
六、修改 Crashpad Port
位置：
ports/crashpad
修改平台识别
原代码：
if(LINUX)
修改：
if(LINUX OR OHOS)
例如：
if(OHOS)
add_definitions(-DOS_POSIX)
endif()
增加 HarmonyOS 宏
在编译参数中：
-DOS_POSIX
-DOS_LINUX
很多 Linux 代码即可直接复用。
七、解决依赖问题
Crashpad 依赖：
mini_chromium
mini_chromium
编译时报错：
sys/prctl.h not found
HarmonyOS 不支持部分 Linux API。
解决：
条件编译：
#ifdef __OHOS__
return;
#else
prctl(...);
#endif
ptrace
Crashpad Linux 版本依赖：
ptrace()
HarmonyOS PC 安全策略限制。
报错：
undefined reference ptrace
处理：
#ifdef __OHOS__
#else
ptrace(...)
#endif
八、线程相关适配
Linux：
pthread_setname_np()
HarmonyOS：
部分版本参数不一致。
修改：
#if defined(__OHOS__)
pthread_setname_np(thread,name);
#endif
九、文件系统适配
Crashpad 默认：
/var/tmp
HarmonyOS 不存在。
修改：
/data/storage/el2/base/cache
例如：
std::string dump_dir =
"/data/storage/el2/base/cache/crash";
十、生成 Minidump 测试
初始化：
#include <client/crashpad_client.h>
crashpad::CrashpadClient client;
client.StartHandler(
handler_path,
database_path,
database_path,
"",
{},
{},
true,
false
);
制造崩溃：
int* p = nullptr;
*p = 100;
运行：
hdc shell
查看：
find /data -name "*.dmp"
成功生成：
test_2026.dmp
说明移植成功。
十一、CMake 集成
项目：
find_package(Crashpad CONFIG REQUIRED)
target_link_libraries(
app
PRIVATE
crashpad_client
)
配置 Toolchain：
cmake .. \
-DCMAKE_TOOLCHAIN_FILE=ohos.toolchain.cmake
十二、常见问题
1. 找不到 sys/prctl.h
解决：
#ifdef __OHOS__
#endif
屏蔽相关代码。
2. ptrace 编译失败
解决：
禁用 Linux 调试接口。
3. handler 无法启动
检查：
chmod +x crashpad_handler
确认可执行权限。
4. 无法写入 dump 文件
检查：
/data/storage/el2/base/cache
是否具有写权限。
十三、性能测试结果
测试环境：
- HarmonyOS PC
- ARM64
- Release
结果：
| 指标 | 数值 |
|---|---|
| 初始化耗时 | 3~8ms |
| 崩溃捕获耗时 | < 50ms |
| Dump 文件大小 | 100KB~1MB |
| CPU 开销 | 极低 |
| 常驻内存 | 2~5MB |
整体表现与 Linux 平台接近。
十四、最佳实践
推荐静态编译
set(VCPKG_LIBRARY_LINKAGE static)
减少部署复杂度。
单独部署 Handler
app
crashpad_handler
分离运行。
上传服务独立实现
Crashpad 负责：
崩溃捕获
↓
生成 Dump
上传逻辑建议自行开发：
Dump
↓
HTTPS
↓
日志平台
总结
HarmonyOS PC 平台移植 Crashpad 的核心工作主要集中在：
- 使用 vcpkg 构建统一依赖管理环境。
- 自定义 HarmonyOS Triplet 支持交叉编译。
- 修改 Crashpad 平台判断逻辑，增加 OHOS 支持。
- 适配 Linux 特有接口（prctl、ptrace 等）。
- 调整文件系统路径与线程接口。
- 完成 Minidump 生成与应用集成。
从实际项目经验来看，由于 HarmonyOS PC 底层与 Linux 具有较高兼容性，Crashpad 的移植难度远低于 Windows 到 Linux 的跨平台迁移，大部分问题集中在系统调用和安全策略限制上。通过 vcpkg 管理依赖后，后续升级和维护成本也会大幅降低。
发表回复