如何为c++项目集成Crashpad或Breakpad进行崩溃报告？ (生产环境调试)_技术教程

Crashpad 比 Breakpad 更适合新项目，因其采用独立 handler 进程提升崩溃稳定性，原生支持 HTTPS 上传、符号解包和进程外 dump 生成，并深度集成 gn/ninja 构建链；Breakpad 的线程内信号处理在栈溢出等极端崩溃下易失效。

Crashpad 和 Breakpad 都能捕获 C++ 程序崩溃时的 minidump，但 Crashpad 是 Chromium 官方推荐的现代替代方案，Breakpad 已基本停止维护；生产环境应优先集成 Crashpad，除非受限于旧系统（如 Windows XP）或已有 Breakpad 基础设施。

为什么 Crashpad 比 Breakpad 更适合新项目

Crashpad 使用独立的 handler 进程（而非 Breakpad 的线程内信号处理），崩溃时更稳定、不易被破坏的堆栈干扰；它原生支持 HTTPS 上传、符号解包、进程外 dump 生成，并与 gn/ninja 构建链深度集成。而 Breakpad 的 ExceptionHandler 在崩溃线程中运行，某些极端崩溃（如栈溢出、堆损坏）下可能无法触发。

Crashpad 默认启用 minidump 的完整内存映射和模块信息，便于还原符号后精准定位源码行
Breakpad 的 client.dll（Windows）或静态链接版本需手动管理符号文件（.sym），且无内置上传逻辑，必须自行实现 HTTP 客户端
Chromium、Electron 12+、VS Code 等主流项目均已迁移到 Crashpad

在 CMake 项目中静态链接 Crashpad 客户端

Crashpad 不提供预编译二进制，必须从源码构建；官方不支持直接用 find_package(Crashpad)，需手动引入其 client 库并链接依赖（如 base, util, snapshot）。

克隆 crashpad 源码（推荐 tag release-2025-09-01 或更新）：

git clone https://chromium.googlesource.com/crashpad/crashpad --branch release-2025-09-01

用 gn gen 生成 Ninja 构建文件，启用 is_component_build = false 和 is_debug = false（生产环境必须关调试符号）

在主项目的 CMakeLists.txt 中添加：

add_subdirectory(path/to/crashpad)
target_link_libraries(your_target PRIVATE crashpad_client crashpad_util crashpad_snapshot)

确保定义 CRASHPAD_LSS_DISABLE_ASM（Linux）或链接 dbghelp.lib + psapi.lib（Windows）

初始化 Crashpad handler 并设置 dump 上传

关键不是“捕获崩溃”，而是让 handler 进程可靠启动、dump 可写入、上传不阻塞主线程——尤其在游戏或音视频类低延迟场景中，上传必须异步且可取消。

立即学习“C++免费学习笔记（深入）”；

调用 crashpad::CrashpadClient::StartHandler() 时，handler 路径必须指向已签名/可信的二进制（macOS Gatekeeper / Windows SmartScreen 会拦截未签名 handler）
database_path 必须是可写的本地目录（如 "./crashpad"），否则 dump 写入失败且无明确错误提示
上传 URL 必须支持 POST multipart/form-data，服务端需解析 upload_file_minidump 字段；Crashpad 不支持自定义 header，认证需通过 URL query（如 ?token=xxx）

示例初始化代码：

crashpad::CrashpadClient client;
client.StartHandler(
    handler,                    // handler 可执行文件路径
    database,                   // database_path
    metrics_dir,                // 可选，用于 crash metrics
    url,                        // upload URL，如 "https://crash.example.com/v1/upload"
    /*annotations=*/{},
    /*arguments=*/{"--no-sandbox"},
    /*restartable=*/true,
    /*initial_integrity_level=*/0);

符号化与生产环境调试的关键细节

没有符号文件，minidump 就是一堆地址；但把 .pdb（Windows）或 .dSYM（macOS）或 .debug（Linux）直接发给用户等于泄露源码结构——必须在服务端完成符号匹配与脱敏。

构建时用 dump_syms（Crashpad 自带工具）导出符号：
```
dump_syms your_app.pdb > your_app.sym
```
，首行格式必须为 MODULE Windows x86_64 xxxxx your_app.exe
Crashpad 生成的 minidump 中含模块 UUID，服务端需按此匹配 .sym 文件，再用 minidump_stackwalk 解析堆栈（注意：该工具不支持 macOS arm64 符号，需交叉编译）
Windows 上若使用 `/DEBUG:FASTLINK`，会导致 PDB UUID 与实际加载模块不一致，必须改用 `/DEBUG:FULL`
避免在 release 构建中 strip 掉所有 debug info：CMake 中应设 set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -gline-tables-only")，平衡体积与调试能力

Crashpad 的 handler 进程模型看似简单，但实际部署时最常出问题的是权限（Linux seccomp/bpf 限制 fork）、路径不可写、HTTPS 证书验证失败（尤其内网自签证书需 patch net 模块），以及符号文件与二进制版本错配——这些都不会报错，只会静默丢弃 dump。