instrument-error-tracking

添加 PostHog 错误跟踪

使用此技能添加 PostHog 错误跟踪，以捕获和监控应用中的异常。在实现功能或审查 PR 后使用此技能，确保错误跟踪包含完整的堆栈跟踪和源映射。如果尚未安装 PostHog，此技能也涵盖 SDK 的初始设置。支持任何平台或语言。

支持的平台：React、Next.js、Web（JavaScript）、Node.js、Python、PHP、Ruby、Ruby on Rails、Go、Elixir、Angular、Svelte、Nuxt、React Native、Flutter、iOS、Android 和 Hono。

说明

请按顺序执行以下步骤：

步骤 1：分析代码库并确定平台。

查找依赖文件（package.json、pubspec.yaml、Podfile、Package.swift、requirements.txt、go.mod、Gemfile、composer.json、mix.exs 等），以确定语言和框架。

查找锁定文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb、go.sum、pubspec.lock、Podfile.lock、Package.resolved、mix.lock），以确定包管理器。

• 检查是否已有 PostHog 配置（SDK 初始化、环境变量等）。如果已经安装并初始化 PostHog，则跳到步骤 4。

步骤 2：研究埋点方式。（如果已配置 PostHog，则跳过。） 2.1. 找到下方与已确定平台匹配的参考文件——它是 SDK 初始化、异常自动捕获和框架专属错误追踪模式的权威来源。现在阅读该文件。 2.2. 如果没有匹配的参考文件，请使用你的常识并进行网页搜索。优先搜索 posthog.com/docs。

步骤 3：安装并初始化 PostHog SDK。（如果已配置 PostHog，则跳过。）

• 为已确定的平台添加 PostHog SDK 包。不要手动编辑 package.json——请使用包管理器的安装命令。
• 按照框架参考说明，确定初始化的位置和方式。

步骤 4：启用异常自动捕获。

• 按照平台参考启用异常自动捕获。无需额外代码即可自动捕获未处理的异常。

步骤 5：手动捕获错误。

• 找出应明确捕获错误的错误边界、catch 块和关键用户流程。
• 在这些位置添加 posthog.captureException() 或平台等效方法。
• 不要改变现有错误处理的基本架构。只进行少量、有针对性的补充。
• 尝试写入文件前，必须立即读取该文件。

步骤 6：上传源映射文件（仅限前端/移动端）。

• 配置源映射文件上传，使堆栈跟踪能够指向原始源代码，而非压缩后的代码包。
• 按照平台专属参考配置上传方式（构建插件、CI 脚本等）。

步骤 7：设置环境变量。

• 检查项目是否已配置 PostHog 环境变量（例如在 .env、.env.local 或框架专属环境文件中）。如果已有有效值，则跳过此步骤。
• 如果缺少 PostHog 项目令牌，请使用 PostHog MCP 服务的 projects-get 工具获取项目的 api_token。如果返回多个项目，请询问用户要使用哪个项目。如果 MCP 服务未连接或未经身份验证，请改为向用户索取 PostHog 项目令牌。
• 对于 PostHog 主机 URL：检查 projects-get MCP 响应中的 region 字段——US 对应 https://us.i.posthog.com，EU 对应 https://eu.i.posthog.com。如果 MCP 响应或现有项目配置中没有区域信息，请询问用户：“您使用的是 PostHog US Cloud 还是 EU Cloud？”不要默认使用 US Cloud。
• 按照框架的命名约定，将这些值写入相应的环境文件。
• 在代码中引用这些环境变量，不要将值硬编码。

步骤 8：验证并清理。

• 检查项目是否有错误。查找 package.json 中的类型检查或构建脚本。
• 确认创建的组件均已实际使用。
• 运行 package.json 中找到的任何 linter 或类似 prettier 的脚本，但仅针对本次会话中编辑或创建的文件。切勿对整个项目代码库运行格式化或 lint。

参考文件

• references/react.md - React 错误跟踪安装
• references/web.md - Web 错误跟踪安装
• references/nextjs.md - Next.js 错误跟踪安装
• references/node.md - Node.js 错误跟踪安装
• references/python.md - Python 错误跟踪安装
• references/django.md - Django
• references/flask.md - Flask
• references/php.md - Php 错误跟踪安装
• references/laravel.md - Laravel
• references/ruby.md - Ruby 错误跟踪安装
• references/ruby-on-rails.md - Ruby on rails 错误跟踪安装
• references/ruby-on-rails.md - Ruby on rails
• references/go.md - Go 错误跟踪安装
• references/dotnet.md - .net 错误跟踪安装
• references/dotnet.md - .net
• references/elixir.md - Elixir 错误跟踪安装
• references/angular.md - Angular 错误跟踪安装
• references/svelte.md - Sveltekit 错误跟踪安装
• references/nuxt-3-7.md - Nuxt 错误跟踪安装（v3.7 及以上）
• references/nuxt-3-6.md - Nuxt 错误跟踪安装（v3.6 及以下）
• references/react-native.md - React native 错误跟踪安装
• references/flutter.md - Flutter 错误跟踪安装
• references/ios.md - Ios 错误跟踪安装
• references/android.md - Android 错误跟踪安装
• references/hono.md - Hono 错误跟踪安装
• references/fingerprints.md - 指纹
• references/alerts.md - 发送错误跟踪警报
• references/monitoring.md - 监控和搜索问题
• references/assigning-issues.md - 将问题分配给队友
• references/upload-source-maps.md - 上传源映射
• references/COMMANDMENTS.md - 集成必须遵循的框架特定规则

每个平台参考文件都包含特定于 SDK 的安装说明和手动捕获模式。请查找与用户技术栈相匹配的文件。

核心原则

• 环境变量：PostHog 密钥始终使用环境变量。切勿将其硬编码。
• 尽量减少改动：在现有错误处理旁添加错误跟踪。不要替换或重构现有代码。
• 优先启用自动捕获：先启用异常自动捕获，再添加手动捕获。
• 源映射：上传源映射，让堆栈跟踪指向原始源代码，而不是压缩后的代码包。
• 在边界处手动捕获：对于不会传播到全局处理程序的错误，在错误边界和 catch 块中使用 captureException()。