前端错误监控-Sentry实战
1. 接入
npm i @sentry/browser @sentry/tracing
# 或框架专用包
npm i @sentry/react @sentry/vue @sentry/nextjs
1.1 Browser 通用
// src/sentry.ts
import * as Sentry from '@sentry/browser'
Sentry.init({
dsn: import.meta.env.VITE_SENTRY_DSN,
environment: import.meta.env.MODE, // production / staging
release: import.meta.env.VITE_APP_VERSION, // 关联 sourcemap
// 性能监控
integrations: [
Sentry.browserTracingIntegration(),
Sentry.replayIntegration({ // 用户操作录制
maskAllText: false,
blockAllMedia: false,
}),
],
tracesSampleRate: 0.1, // 采 10% 性能事件
replaysSessionSampleRate: 0.01, // 采 1% 录制
replaysOnErrorSampleRate: 1.0, // 错误时 100% 录
// 噪声过滤
ignoreErrors: [
'ResizeObserver loop',
'Non-Error promise rejection',
/Network request failed/,
],
beforeSend(event, hint) {
// 过滤特定错误
if (event.exception?.values?.[0]?.value?.includes('cancelled')) {
return null
}
return event
},
})
// 设置用户上下文
Sentry.setUser({ id: user.id, email: user.email })
1.2 Next.js
npx @sentry/wizard@latest -i nextjs
自动生成 sentry.client.config.ts、sentry.server.config.ts、sentry.edge.config.ts、next.config.js 配置。
1.3 React
import { ErrorBoundary } from '@sentry/react'
<ErrorBoundary fallback={({ error }) => <ErrorPage error={error} />}>
<App />
</ErrorBoundary>
2. SourceMap 上传
生产 JS 是压缩的，没 sourcemap 看到的是 a.js:1:12345。Sentry 上传 sourcemap 后能映射回源码 App.tsx:42:5。
# 安装 cli
npm i -D @sentry/cli
# 上传（CI 里）
sentry-cli sourcemaps inject ./dist
sentry-cli sourcemaps upload \
--org my-org \
--project frontend \
--release ${RELEASE_VERSION} \
./dist
构建配置必须输出 sourcemap：
// vite.config.ts
export default {
build: {
sourcemap: true, // 生成 .map
// 生产不暴露给浏览器（sourcemap 文件不部署到 CDN）
}
}
sourcemap 不能公开：暴露源码 + 安全风险。CI 上传到 Sentry 后从 dist 删除。
3. 关键概念
3.1 Issue / Event
- Event：单次错误发生
- Issue：相同错误的聚合（按堆栈指纹）
Sentry 自动 group，相同错误堆栈合一个 issue。
3.2 Release
每次部署绑定一个 release，关联代码、sourcemap、commits。
Sentry.init({ release: 'frontend@1.2.3' })
CI 里关联 commits：
sentry-cli releases new ${VERSION}
sentry-cli releases set-commits ${VERSION} --auto
sentry-cli releases finalize ${VERSION}
sentry-cli releases deploys ${VERSION} new -e production
UI 上能看到"这个 issue 在哪些 commit 引入"。
3.3 Environment
environment: 'production'
生产/预发分开看，不混。
4. 性能监控
Sentry.init({
integrations: [Sentry.browserTracingIntegration()],
tracesSampleRate: 0.1,
})
自动采集：
- 页面加载（FCP / LCP / CLS / TTFB / FID）
- 路由变化
- HTTP 请求（fetch / XHR）
- 组件渲染（React 集成）
手动埋点：
const transaction = Sentry.startTransaction({ name: 'expensive-task' })
const span = transaction.startChild({ op: 'compute' })
// ... 执行
span.finish()
transaction.finish()
5. Session Replay
录用户操作（DOM 变化 + 输入），错误发生时能回放：
Sentry.replayIntegration({
maskAllText: true, // 文本打码（隐私）
maskAllInputs: true,
blockAllMedia: false,
})
存储成本高，按需采样。
6. 告警规则
Sentry → Alerts → Issue Alerts：
- 新 issue：第一次出现
- 回归：已 resolved 又出现
- 高频：1 小时内 > 100 次
- 影响用户多：> 100 用户
通道：邮件 / Slack / 飞书 / 钉钉 / PagerDuty / Webhook。
7. 团队协作
- Owner 规则：按文件路径自动分配 issue 给团队
/src/checkout/ @checkout-team/src/auth/ @auth-team
- Assigned：手动分配
- Resolved：标记修复（关联 commit / PR）
- Ignored：暂时不管
8. 数据隐私
maskAllInputs输入框打码beforeSend过滤敏感字段- IP 地址脱敏：
sendDefaultPii: false - 私有自部署：Sentry 开源版可自托管
9. 自托管 Sentry
git clone https://github.com/getsentry/self-hosted
cd self-hosted
./install.sh
docker compose up -d
资源需求：4C 8G + 50GB 起步。中型团队 OK，大量数据需要扩 Snuba/Clickhouse。
10. 国内替代
| 工具 | 特点 |
|---|---|
| Sentry SaaS | 国外节点，部分网络慢 |
| Sentry 自托管 | 国内自部署最干净 |
| 阿里云 ARMS（前端监控） | 国内 SaaS |
| FundeBug | 国内厂商 |
| 字节 Slardar / 腾讯 Aegis | 内部自建 |
11. 常见反模式
- 不上传 sourcemap：堆栈无法定位
- sourcemap 部署到 CDN：源码暴露
- 采样率 100%：免费版立即用完配额
- 不过滤噪声：ResizeObserver、cancelled 等占满 issue
- 不设 release：错误归不到具体版本
- PII 直接发：信用卡 / 手机号上 Sentry
- 告警频道一个：所有团队 issue 都来，没人看
- 不做 owner 分配：issue 没人认领