diagnosing-stacktrace-symbolication

诊断堆栈跟踪符号化

符号化是一个跨平台术语，涵盖 JavaScript 源映射查找、Hermes 函数偏移量解析、Proguard / R8 反混淆，以及 dSYM 地址到行号的查找——这些操作都会将经过缩小或混淆的堆栈帧还原为可读的文件、函数和行号。

将用户的构建和 PostHog 符号集作为一条流水线进行排查：构建配置 -> 生成的符号制品（JavaScript 源映射、Hermes 映射、Proguard 映射文件或 dSYM 包）-> PostHog 中已上传的符号集 -> 捕获的错误堆栈帧。按顺序检查这四项，通常就能找出大多数问题。

平台

平台	符号数据类型	参考
JavaScript / TypeScript Web	source-and-map	javascript.md
React Native（Hermes）	hermes	即将推出
Android（Proguard / R8）	proguard	即将推出
iOS / macOS（dSYM）	apple-dsym	即将推出

工作流的第 3 步（在 PostHog 中查找符号集）在所有平台上都相同——posthog-cli symbol-sets extract 可处理所有四种容器类型。第 1、2 步以及特定于平台的故障模式请参阅各平台的参考文档。

工作流

第 1 步 - 找出符号数据的生成和上传方式

查看应用仓库的构建脚本和 PostHog 上传配置。确认负责上传的 PostHog 包（@posthog/rollup-plugin、@posthog/webpack-plugin、@posthog/nextjs-config、@posthog/nuxt 或直接使用 posthog-cli），以及它处理的目录或资源。有关特定构建工具的配置检查，请参阅平台参考文档。

调试时，最好使用上传后仍会将符号制品保留在磁盘上的构建，这样就能将本地制品与 PostHog 收到的内容进行比较。以下是使用 Vite 插件的 JavaScript 示例（其他构建工具的等效设置请参阅平台参考文档）：

sourcemaps: {
  enabled: true,
  deleteAfterUpload: false,
}

第 2 步 - 构建并检查本地制品

运行会上传符号的生产构建，然后在本地检查生成的文件。具体文件和辅助命令因平台而异——有关辅助命令、预期文件格式以及常见构建时陷阱（尤其是映射内容为空的误报：这看起来像是上传问题，实际上是打包工具的配置问题），请参阅平台参考文档。

如果本地制品看起来就有问题，请先修复构建，再排查 PostHog 上传问题。

第 3 步 - 检查 PostHog 中的符号集

使用专用 MCP 工具查找 ref 与捕获帧的 chunk_id 匹配的符号集——这些工具会自动处理身份验证、项目范围和分页：

• 使用 posthog:error-tracking-symbol-sets-list 并设置 ref=<chunk_id>，返回匹配的行。
• 使用 posthog:error-tracking-symbol-sets-retrieve 并提供 ID，返回相同的数据结构（并确认权限）。
• posthog:error-tracking-symbol-sets-download-retrieve 会返回一个指向已上传符号数据文件、有效期为一小时的预签名 URL。请立即下载；除非用户明确要求，否则不要回显该 URL。

如果无法访问 MCP，可在 PostHog 界面的 Project settings > Error tracking > Symbol sets 中找到相同的数据。

解读该行：

• ref 必须与捕获帧的 chunk_id 匹配。
• last_used 更新表示 PostHog 找到了该符号集并已加载它，但不能保证该帧已解析。
• has_uploaded_file: false 表示上传未完成。
• failure_reason 非空表示 PostHog 无法解析或加载已上传的符号数据。

下载的文件是 PostHog 符号数据容器（经过压缩的 Rust 编码负载），并非纯 JSON。使用 posthog-cli 提取：

posthog-cli symbol-sets extract symbolset.bin -o ./extracted
# or, without installing globally:
#   npx @posthog/cli symbol-sets extract symbolset.bin -o ./extracted
#   bunx @posthog/cli symbol-sets extract symbolset.bin -o ./extracted

posthog-cli symbol-sets extract 支持所有四种符号集类型（source-and-map、hermes、proguard、dSYM），并会将提取的文件写入输出目录。提取完成后，使用平台参考文档中的辅助工具进行总结。

第 4 步 - 比较本地、已上传和已提供的文件

根据失败位置确定要比较的内容：

• 本地构建产物为空且已上传的构建产物也为空：构建工具生成了不可用的符号。
• 本地构建产物有效但已上传的构建产物为空：上传处理选择或打包了错误的数据。
• 已上传的构建产物有效，但生产环境中的堆栈仍经过缩小或混淆：比较已部署二进制文件的字节与随符号一起上传的二进制文件。
• Token not found：PostHog 已加载符号数据，但捕获的生成位置与已上传构建产物中的任何标记都不匹配。通常意味着上传后二进制文件发生了变化、捕获的行／列位置不正确（JavaScript）、帧偏移不正确（Hermes／dSYM），或符号覆盖存在问题。

第 5 步 - 修复最可能的问题层

适用于所有平台的修复方法：

• 等最终构建产物生成后再上传符号，不要在后续步骤改写构建产物前上传。
• 使用最新版本的 PostHog 构建插件和 posthog-cli。
• 如果之前已使用相同的 ref 上传了不同内容，请有意重新上传已更改的资源。
• 移除会在上传后更改所提供二进制文件的部署时转换（CDN 缩小、边缘重写、压缩）。

平台专属修复方法请参阅平台参考文档。

捕获帧检查

从受影响的 PostHog 错误事件中，收集一个经过缩小的应用帧：

• filename
• line 或 lineno
• column 或 colno
• function
• chunk_id（或平台对应的符号集 ref）
• 任何 resolve_failure，尤其是 Token not found

帧的 filename 应与已部署的二进制文件 URL 匹配。chunk_id 应与符号集的 ref 匹配。捕获的生成位置应指向与符号数据一同上传的同一个二进制文件。

失败情况矩阵（跨平台）

证据	可能原因	后续检查
帧中没有 chunk_id	缺少 Chunk ID 注入，或 SDK 帧解析器未映射文件名	检查已部署的二进制文件和原始帧文件名。
缺少符号集行	上传到了其他 PostHog 项目/主机，或跳过了此资源	比较插件的 projectId、host 和 ref。
has_uploaded_file: false	上传未完成	检查构建日志；将 posthog-cli 输出与符号集行进行比较。
failure_reason 非空	PostHog 无法解析上传的符号数据	通过步骤 3 下载并检查解压后的内容。
上传的构建产物有效，但已部署的二进制文件不同	部署/CDN/构建后转换在上传后更改了二进制文件	将已部署的字节内容与本地构建输出进行比较。
Token not found	捕获的位置在上传的符号数据中没有对应的令牌	验证捕获位置、已部署的二进制文件身份和符号数据覆盖范围。

平台特定的失败模式（空的 mappings、缺少 sourcesContent、Hermes 函数偏移不匹配、 Proguard 类名变更、dSYM UUID 不匹配）详见平台参考文档。