Back to Details

error-tracking-web

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PostHog error tracking for Web (JavaScript)

面向Web（JavaScript）的PostHog错误追踪

This skill helps you add PostHog error tracking to Web (JavaScript) applications.
本技能可帮助你在Web（JavaScript）应用中添加PostHog错误追踪功能。

Reference files

参考文件

  • references/web.md
    - Web error tracking installation - docs
  • references/fingerprints.md
    - Fingerprints - docs
  • references/alerts.md
    - Send error tracking alerts - docs
  • references/monitoring.md
    - Monitor and search issues - docs
  • references/assigning-issues.md
    - Assign issues to teammates - docs
  • references/upload-source-maps.md
    - Upload source maps - docs
Consult the documentation for API details and framework-specific patterns.
  • references/web.md
    - Web错误追踪安装文档
  • references/fingerprints.md
    - 指纹识别文档
  • references/alerts.md
    - 发送错误追踪告警文档
  • references/monitoring.md
    - 监控与搜索问题文档
  • references/assigning-issues.md
    - 向团队成员分配问题文档
  • references/upload-source-maps.md
    - 上传源映射文档
如需API详情和特定框架的实现模式，请查阅相关文档。

Key principles

核心原则

  • Environment variables: Always use environment variables for PostHog keys and host URLs. Never hardcode them.
  • Minimal changes: Add error tracking alongside existing error handling. Don't replace or restructure existing error handling code.
  • Autocapture first: Enable exception autocapture in the SDK initialization before adding manual captures.
  • Source maps: Upload source maps so stack traces resolve to original source code, not minified bundles.
  • Manual capture for boundaries: Use 
    captureException()
    at error boundaries and catch blocks for errors that don't propagate to the global handler.
  • 环境变量：始终使用环境变量存储PostHog密钥和主机URL，绝不要硬编码。
  • 最小改动：在现有错误处理基础上添加错误追踪，不要替换或重构现有错误处理代码。
  • 自动捕获优先：在SDK初始化时启用异常自动捕获，再添加手动捕获逻辑。
  • 源映射：上传源映射，以便将堆栈跟踪解析为原始源代码，而非压缩后的包文件。
  • 边界处手动捕获：在错误边界和catch块中使用
    captureException()
    ，捕获那些不会传播到全局处理器的错误。

Framework guidelines

框架指南

  • Remember that source code is available in the node_modules directory
  • Check package.json for type checking or build scripts to validate changes
  • posthog-js is the JavaScript SDK package name
  • posthog.init() MUST be called before any other PostHog methods (capture, identify, etc.)
  • posthog-js is browser-only — do NOT import it in Node.js or server-side contexts (use posthog-node instead)
  • Autocapture is ON by default with posthog-js (tracks clicks, form submissions, pageviews). Do NOT disable autocapture unless the user explicitly requests it.
  • NEVER send PII in posthog.capture() event properties — no emails, full names, phone numbers, physical addresses, IP addresses, or user-generated content
  • PII belongs in posthog.identify() person properties (email, name, role), NOT in capture() event properties
  • Call posthog.identify(userId, { email, name, role }) on login AND on page refresh if the user is already logged in
  • Call posthog.reset() on logout to unlink future events from the current user
  • For SPAs without a framework router, capture pageviews with posthog.capture($pageview) or use the capture_pageview history_change option in init for History API routing
  • 请注意源代码可在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地址或用户生成内容
  • 个人可识别信息应放在posthog.identify()的用户属性中（如邮箱、姓名、角色），而非capture()的事件属性中
  • 用户登录时以及用户已登录状态下的页面刷新时，调用posthog.identify(userId, { email, name, role })
  • 用户登出时调用posthog.reset()，解除后续事件与当前用户的关联
  • 对于无框架路由的单页应用（SPA），可使用posthog.capture($pageview)捕获页面浏览，或在初始化时使用history_change选项中的capture_pageview来适配History API路由