HarmonyOS鸿蒙PC平台三方库移植使用vcpkg 移植 Crashpad 过程实战总结

lichongyang

3 小时前

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

官方仓库：

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

编译时报错：

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 &lt;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

是否具有写权限。

十三、性能测试结果