如何用 Gurulu 设置错误追踪

大多数分析平台止步于页面浏览和点击。Gurulu 则更进一步，在你的分析数据之外，还捕获未处理的异常、Promise 拒绝和网络错误。本指南将带你从零开始设置错误追踪。

为什么要在你的分析平台中追踪错误？

当错误存在于一个独立的工具中时，你会失去上下文。你知道某个用户看到了一个错误，但你不知道他们在此之前或之后做了什么。Gurulu 会将错误与完整的会话时间线——页面浏览、点击、表单提交——关联起来，让你能准确看到是什么导致了崩溃，以及用户是恢复了还是跳出了。

第 1 步：添加错误追踪脚本

如果你已经安装了主追踪器 t.js，那么错误追踪默认就已激活。Gurulu 会自动捕获 window.onerror 和 unhandledrejection 事件。

若需进行带堆栈跟踪反混淆的高级错误追踪，请添加专用的错误脚本：

<script
  src="https://cdn.gurulu.io/t-errors.js"
  data-site-id="YOUR_SITE_ID"
  data-token="YOUR_TOKEN"
  async
></script>

或通过 npm 包安装：

import { initErrors } from '@gurulu/web';

initErrors({
  siteId: 'YOUR_SITE_ID',
  token: 'YOUR_TOKEN',
  captureConsole: true,   // optional: capture console.error
  captureNetwork: true,   // optional: capture failed fetch/XHR
});

第 2 步：上传源映射（Source Map）

生产环境的打包文件经过压缩，导致堆栈追踪难以阅读。Gurulu 支持上传源映射，让你能看到原始的文件名、行号和函数名。

在构建流水线中使用 CLI 上传源映射：

npx @gurulu/cli sourcemaps upload \
  --site-id YOUR_SITE_ID \
  --release v1.2.0 \
  --directory ./dist

源映射会被安全存储，绝不会暴露给最终用户。你也可以通过设置 GURULU_TOKEN 环境变量，在 CI 中配置自动上传。

第 3 步：在仪表盘中查看错误

前往仪表盘的「错误」标签页。你会看到按指纹（fingerprint）分组的错误——相似的堆栈追踪会被折叠为同一个问题。每个问题都会提供：

错误次数与受影响用户数 ——衡量问题的影响范围
首次与最近一次出现时间 ——它何时出现，以及是否仍然活跃
堆栈追踪 ——如果上传了源映射，则会显示反混淆后的内容
会话回放链接 ——直接跳转到错误发生时的用户会话
浏览器与操作系统分布 ——识别特定环境下的缺陷

第 4 步：设置告警

当出现新的错误类型，或现有错误突增时，Gurulu 可以通知你。前往「设置 > 告警」创建规则。你可以将告警路由到 Slack、电子邮件或任意 webhook 端点。

高效错误追踪的小贴士

为发布版本打标签。 始终传入发布版本标识符，这样你就能按部署来筛选错误，并快速发现某个新发布是否引入了回归问题。

添加上下文。 使用 gurulu.setUser() 将用户身份关联到错误。这样就能轻松看出哪些客户受到影响，并主动联系他们。

监控网络错误。 启用 captureNetwork 以捕获失败的 API 调用。这些往往是空白页面和界面崩溃背后的根本原因。