error-tracking-web

PostHog Web（JavaScript）错误跟踪

此技能可帮助你为 Web（JavaScript）应用添加 PostHog 错误跟踪。

参考文件

• references/web.md - Web 错误跟踪安装文档
• references/fingerprints.md - 指纹文档
• references/alerts.md - 发送错误跟踪警报文档
• references/monitoring.md - 监控和搜索问题文档
• references/assigning-issues.md - 将问题分配给团队成员的文档
• references/upload-source-maps.md - 上传源代码映射文档

请参阅文档，了解 API 详情和针对特定框架的模式。

核心原则

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

框架指南

• 请记住，node_modules 目录中有源代码。
• 检查 package.json 中的类型检查或构建脚本，以验证更改。
• posthog-js 是 JavaScript SDK 的包名。
• 必须先调用 posthog.init()，才能调用任何其他 PostHog 方法（capture、identify 等）。
• posthog-js 仅适用于浏览器 — 不要在 Node.js 或服务器端上下文中导入它（请改用 posthog-node）。
• posthog-js 默认已启用自动捕获（跟踪点击、表单提交和页面浏览）。除非用户明确要求，否则不要禁用自动捕获。
• 切勿在 posthog.capture() 事件属性中发送 PII — 不要包含电子邮件、全名、电话号码、实际地址、IP 地址或用户生成的内容。
• PII 应放在 posthog.identify() 的用户属性中（email、name、role），而不是 capture() 事件属性中。
• 在用户登录时以及页面刷新且用户已处于登录状态时，调用 posthog.identify(userId, { email, name, role })。
• 用户登出时调用 posthog.reset()，以解除后续事件与当前用户的关联。
• 对于没有框架路由器的 SPA，可使用 posthog.capture($pageview) 捕获页面浏览，或在 init 中使用 capture_pageview history_change 选项处理 History API 路由。