React 错误追踪：Sentry 集成实战

pnpm add @sentry/react

// src/lib/sentry.ts
import * as Sentry from "@sentry/react";

export function initSentry() {
  Sentry.init({
    dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
    // 关键：环境标识，让你在 Sentry 后台区分 prod / staging / dev
    environment: process.env.NODE_ENV,
    // 发布版本号，绑 release 追踪（见第五节）
    release: process.env.NEXT_PUBLIC_SENTRY_RELEASE,
    // 采样率，见下文解释
    tracesSampleRate: 0.2,
    // 默认就是 1.0，错误事件 100% 上报；高 QPS 站点才需要降
    sampleRate: 1.0,
    // 关掉开发环境的自动上报，别污染数据
    enabled: process.env.NODE_ENV === "production",
  });
}

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampler: (samplingContext) => {
    // 关键页面全量采样，边缘页面低采样
    if (samplingContext.transactionName?.includes("/checkout")) {
      return 1.0; // 支付链路，一条都不漏
    }
    if (samplingContext.transactionName?.includes("/api/")) {
      return 0; // 接口调用不单独采样
    }
    return 0.1; // 其余 10%
  },
});

// src/components/ErrorBoundary.tsx
import * as React from "react";
import * as Sentry from "@sentry/react";

interface Props {
  children: React.ReactNode;
  fallback: (error: Error, reset: () => void) => React.ReactNode;
  /** 区分页面级 / 区块级，便于后台聚合 */
  scope?: string;
}

interface State {
  error: Error | null;
}

export class ErrorBoundary extends React.Component<Props, State> {
  state: State = { error: null };

  static getDerivedStateFromError(error: Error): State {
    // 更新 state，触发 fallback UI 渲染
    return { error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
    // 这里把错误连同 React 组件栈一起上报
    Sentry.withScope((scope) => {
      scope.setTag("error_boundary", this.props.scope ?? "unknown");
      // componentStack 是 Error Boundary 独有的金子，比普通调用栈更能定位组件
      scope.setContext("react", { componentStack: errorInfo.componentStack });
      Sentry.captureException(error);
    });
  }

  reset = () => this.setState({ error: null });

  render() {
    if (this.state.error) {
      return this.props.fallback(this.state.error, this.reset);
    }
    return this.props.children;
  }
}

// 页面最外层兜底：整个页面炸了也有个说法
<ErrorBoundary
  scope="page"
  fallback={(error, reset) => (
    <CrashScreen error={error} onRetry={reset} />
  )}
>
  <App />

  {/* 局部兜底：某个挂件炸了，不影响整页 */}
  <ErrorBoundary
    scope="recommendation-widget"
    fallback={() => <div>推荐暂时不可用</div>}
  >
    <RecommendationWidget />
  </ErrorBoundary>
</ErrorBoundary>

at e.exports (chunk-A3F9B2.js:1:28471)
at t.render (chunk-A3F9B2.js:1:18903)
at Object.Lc (framework-7c1.js:22:91023)

// next.config.ts（节选，@sentry/nextjs 会接管，详见第八节）
// 如果是纯 Vite/Webpack 项目，思路一致：build 时输出 .map 文件
const config = {
  // 关键：让打包器产出 source map
  productionBrowserSourceMaps: true, // Next.js
  // Vite: build.sourcemap = 'hidden'（hidden 意味着不在 bundle 里引用 .map，
  // 也就是浏览器拿不到 map，但磁盘上有，给上传用）
};

# 用 CLI 手动上传，适合脚本化
SENTRY_AUTH_TOKEN=xxx sentry-cli sourcemaps upload \
  --org my-org \
  --project my-frontend \
  --release $(git rev-parse HEAD) \
  ./dist

# .github/workflows/deploy.yml 节选
- name: Build
  run: pnpm build            # 产出带 source map 的产物
- name: Upload sourcemaps to Sentry
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  run: |
    sentry-cli sourcemaps upload \
      --release ${{ github.sha }} \
      --url-prefix "~/static" \  # 关键：告诉 Sentry 这些文件在生产环境的 URL 前缀
      ./out/_next/static
- name: Deploy
  run: ./deploy.sh           # 然后再部署

// 1. 定义 release 标识（推荐用 commit SHA，绝对唯一）
// CI 里注入：export NEXT_PUBLIC_SENTRY_RELEASE=$(git rev-parse HEAD)

// 2. Sentry.init 里带上它
Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  release: process.env.NEXT_PUBLIC_SENTRY_RELEASE, // 第四节已提
});

// 3. source map 上传时绑定同一个 release（第四节 CLI 命令里的 --release）
// 4. （可选）发版后创建一次 commit，让 Sentry 知道这次发布

# 发版后，告诉 Sentry "这个 release 部署了"
sentry-cli releases new $RELEASE
sentry-cli releases set-commits $RELEASE --auto   # 关联对应的 git commit
sentry-cli releases finalize $RELEASE

import * as Sentry from "@sentry/react";

async function checkout(cartId: string) {
  // 手动起一个性能事务，追踪结账全流程
  const transaction = Sentry.startTransaction({
    name: "checkout-flow",
    op: "checkout",
  });
  Sentry.getCurrentHub().configureScope((scope) => scope.setSpan(transaction));

  try {
    const span1 = transaction.startChild({ op: "validate", description: "校验库存" });
    await validateStock(cartId);
    span1.finish();

    const span2 = transaction.startChild({ op: "pay", description: "调用支付" });
    await pay(cartId);
    span2.finish();
  } finally {
    transaction.finish(); // 不调 finish 的事务不会上报，这是常见坑
  }
}

import * as Sentry from "@sentry/react";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  beforeSend(event) {
    return scrubEvent(event);
  },
});

const PII_PATTERNS: Array<[RegExp, string]> = [
  [/1[3-9]\d{9}/g, "[PHONE]"], // 手机号
  [/\b[\w.+-]+@[\w-]+\.[\w.-]+\b/g, "[EMAIL]"], // 邮箱
  [/\b\d{15}(\d{2}[\dXx])?\b/g, "[ID]"], // 身份证
  [/"(?:token|password|secret|apiKey)"\s*:\s*"[^"]*"/gi, '"$1":"[REDACTED]"'],
];

function scrubEvent(event: Sentry.Event): Sentry.Event | null {
  // 1. 清请求 URL 里的 query 参数（最容易带 token）
  if (event.request?.url) {
    event.request.url = stripQueryParams(event.request.url);
  }

  // 2. 清面包屑里的 PII（接口 URL、消息文本）
  event.breadcrumbs = event.breadcrumbs?.map((b) => ({
    ...b,
    data: b.data && scrubObject(b.data),
  }));

  // 3. 清错误对象里的额外字段
  if (event.exception?.values) {
    for (const ex of event.exception.values) {
      ex.stacktrace?.frames?.forEach((f) => {
        if (f.vars) f.vars = scrubObject(f.vars);
      });
    }
  }

  // 4. 用户主动设置的身份信息（如非必要别上报精确身份）
  if (event.user) {
    event.user.email = event.user.email ? "[EMAIL]" : undefined;
    event.user.ip_address = "[REDACTED]";
    // 保留 user.id（内部 ID）做用户聚合够用，但别带真实身份
  }

  return event;
}

function scrubObject(obj: Record<string, unknown>): Record<string, unknown> {
  const out: Record<string, unknown> = {};
  for (const [key, value] of Object.entries(obj)) {
    if (/token|password|secret|authorization/i.test(key)) {
      out[key] = "[REDACTED]";
      continue;
    }
    if (typeof value === "string") {
      out[key] = PII_PATTERNS.reduce((s, [re, tag]) => s.replace(re, tag), value);
    } else {
      out[key] = value;
    }
  }
  return out;
}

function stripQueryParams(url: string): string {
  try {
    const u = new URL(url);
    u.searchParams.forEach((_, key) => {
      if (/token|auth|key|email|phone/i.test(key)) {
        u.searchParams.set(key, "[REDACTED]");
      }
    });
    return u.toString();
  } catch {
    return url;
  }
}

pnpm add @sentry/nextjs
# 官方向导自动生成配置文件、改 next.config
npx @sentry/wizard@latest -i nextjs

// sentry.client.config.ts —— 浏览器端
import * as Sentry from "@sentry/nextjs";
Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 0.2,
  replaysSessionSampleRate: 0.1,    // 会话回放：常态 10% 采样
  replaysOnErrorSampleRate: 1.0,    // 出错的会话 100% 回放
});

// sentry.server.config.ts —— Node 服务端（API Route / Server Action）
import * as Sentry from "@sentry/nextjs";
Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 0.2,
});

// sentry.edge.config.ts —— Edge Runtime（中间件）
import * as Sentry from "@sentry/nextjs";
Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 0.2,
});

// instrumentation.ts —— 项目根目录
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
  // client 配置由 Next.js 自动注入，不在这里管
}

// next.config.ts
import { withSentryConfig } from "@sentry/nextjs";

const nextConfig = { /* 你的其它配置 */ };

export default withSentryConfig(nextConfig, {
  // 自动上传 source map（构建时，依赖 SENTRY_AUTH_TOKEN 环境变量）
  sourcemaps: {
    deleteAfterCompile: true, // 上传完从构建产物里删掉，不进 CDN
  },
  // release 标识
  release: { name: process.env.NEXT_PUBLIC_SENTRY_RELEASE },
  // 关掉发版时往 Sentry 提交 commit（避免 CI 权限问题）
  disableClientWebpackPlugin: false,
  // 隐藏 console.log 之外的 org/project 默认配置
  org: process.env.SENTRY_ORG,
  project: process.env.SENTRY_PROJECT,
});

// 配合代码里打 tag，让告警规则能精确匹配
Sentry.withScope((scope) => {
  scope.setTag("module", "payment");
  scope.setTag("severity", "revenue-impacting");
  Sentry.captureException(err);
});