在实现功能或审查 PR 后为应用接入 PostHog…

当你需要为应用添加异常捕获与监控、确保错误带有完整堆栈和 source map 时，按平台接入 PostHog 错误追踪。

适用场景

解决思路

1. STEP 1：分析代码库并检测平台。查找依赖文件（package.json、pubspec.yaml、Podfile、Package.swift、requirements.txt、go.mod、Gemfile、composer.json、mix.exs 等）以确定语言和框架；查找 lockfile（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb、go.sum、pubspec.lock、Podfile.lock、Package.resolved、mix.lock）以确定包管理器；检查是否已有 PostHog 设置（SDK 初始化、环境变量等），若已安装并初始化则跳到 STEP 4。
2. STEP 2：研究接入方式（若 PostHog 已设置则跳过）。2.1 在下方参考文件中找到与检测到的平台匹配的文件——它是 SDK 初始化、异常自动捕获和框架特定错误追踪模式的权威来源，立即阅读。2.2 若无匹配参考，回退到通用知识并网络搜索，以 posthog.com/docs 作为主要搜索来源。
3. STEP 3：安装并初始化 PostHog SDK（若 PostHog 已设置则跳过）。为检测到的平台添加 PostHog SDK 包；不要手动编辑 package.json——使用包管理器的安装命令；按框架参考文件确定初始化的位置和方式。
4. STEP 4：启用异常自动捕获。按平台参考文件启用异常自动捕获，它会自动捕获未处理异常而无需额外代码。
5. STEP 5：添加手动错误捕获。识别错误边界、catch 块和关键用户流程中应显式捕获错误的位置；在这些位置添加 `posthog.captureException()` 或平台等价方法；不要改变现有错误处理的基本架构，新增应最小且精准；在尝试写入文件前必须先读取该文件。
6. STEP 6：上传 source map（仅前端/移动端）。配置 source map 上传，使堆栈能解析到原始源代码而非压缩后的 bundle；按平台特定参考文件进行上传配置（构建插件、CI 脚本等）。
7. STEP 7：设置环境变量。检查项目是否已配置 PostHog 环境变量（如 `.env`、`.env.local` 或框架特定 env 文件），若已有有效值则跳过此步；若缺少 PostHog project token，使用 PostHog MCP 服务器的 `projects-get` 工具获取项目的 `api_token`，若返回多个项目则询问用户使用哪个，若 MCP 服务器未连接或未认证则改为向用户索取 PostHog project token；对于 PostHog host URL：检查 `projects-get` MCP 响应中的 `region` 字段——`US` 对应 `https://us.i.posthog.com`，`EU` 对应 `https://eu.i.posthog.com`，若无法从 MCP 响应或现有项目配置获得 region，则询问用户：“Are you on PostHog US Cloud or EU Cloud?”，不要默认假设为 US Cloud；按框架命名约定将这些值写入合适的 env 文件；在代码中引用这些环境变量而非硬编码。
8. STEP 8：验证并清理。检查项目是否有错误，查看 package.json 中的类型检查或构建脚本；确保创建的任何组件确实被使用；运行 package.json 中找到的 linter 或 prettier 类脚本，但仅针对本次会话中编辑或创建的文件，绝不要对整个项目代码库运行格式化或 lint。
9. 关键原则：环境变量——PostHog 密钥始终使用环境变量，绝不硬编码；最小改动——在现有错误处理旁添加错误追踪，不要替换或重构现有代码；自动捕获优先——在添加手动捕获前先启用异常自动捕获；source map——上传 source map 使堆栈解析到原始源代码而非压缩 bundle；边界手动捕获——在错误边界和 catch 块对不会传播到全局处理器的错误使用 `captureException()`。

适用边界 · 注意事项

• 尚未确定目标平台或框架时，无法选择对应的参考文件与安装方式
• 项目已完整配置 PostHog 且无需新增错误追踪时（STEP 2、3 可跳过）
• 无法访问 PostHog MCP 服务器且用户也无法提供 project token 或 region 时