vault backup: 2026-06-09 23:15:17

claude-code-best/docs/internals/sentry-setup.md

@@ -1,17 +1,17 @@
 ---
-title: "自定义 Sentry 错误上报配置"
-description: "通过环境变量连接自托管或 Cloud Sentry，实现 CLI 运行时的错误捕获与上报。不配置则完全静默。"
-keywords: ["sentry", "错误上报", "监控", "DSN", "自托管"]
+tags: [sentry, 错误上报, 监控, claude-code, 自托管]
+create time: 2026-06-09 22:30
 ---
 
+# 自定义 Sentry 错误上报配置
+
 ## 概述
 
-Claude Code 支持通过 Sentry 捕获运行时异常并上报到你自己指定的 Sentry 实例。
+Claude Code 支持通过 Sentry 捕获运行时异常并上报到你自己指定的 Sentry 实例。只需设置 `SENTRY_DSN` 环境变量即可启用，未配置时所有 Sentry 调用均为 no-op，零开销。
 
-- **配置了 `SENTRY_DSN`**：自动初始化 Sentry SDK，捕获未处理异常和关键错误
-- **未配置**：所有 Sentry 调用均为 no-op，零开销
+## 正文
 
-## 环境变量
+### 环境变量
 
 | 变量 | 必填 | 说明 |
 |---|---|---|
@@ -19,47 +19,45 @@ Claude Code 支持通过 Sentry 捕获运行时异常并上报到你自己指定
 
 只需要这一个变量，设置后即启用。
 
-## 使用方式
+### 使用方式
 
-### 自托管 Sentry
+**自托管 Sentry**
 
 ```bash
 SENTRY_DSN=https://public_key@your-sentry.example.com/123 \
 bun run dev
 ```
 
-### Sentry Cloud (SaaS)
+**Sentry Cloud (SaaS)**
 
 ```bash
 SENTRY_DSN=https://public_key@o123456.ingest.sentry.io/789 \
 bun run dev
 ```
 
-### 不使用 Sentry（默认行为）
+**不使用 Sentry（默认行为）**
 
 ```bash
 bun run dev
 # SENTRY_DSN 未设置，所有 sentry 函数为 no-op
 ```
 
-## Sentry 服务端配置
-
-### 步骤
+### Sentry 服务端配置
 
 1. **部署 Sentry 实例**（Docker 自托管 或 使用 [sentry.io](https://sentry.io) Cloud）
 2. **创建 Project**，选择 **Node.js** 平台
-3. 获取项目的 **DSN**（Settings → Projects → Client Keys → DSN）
+3. 获取项目的 **DSN**（Settings -> Projects -> Client Keys -> DSN）
 4. 将 DSN 设置为 `SENTRY_DSN` 环境变量
 
-## 功能详情
+### 功能详情
 
-### 错误捕获
+**错误捕获**
 
 - **自动捕获**：`SentryErrorBoundary` 包裹关键 React 组件，捕获渲染错误
 - **手动上报**：`errorLogSink` 在写入错误日志时同步上报到 Sentry
 - **优雅关闭**：进程退出时 `closeSentry()` 确保事件发送完毕（2s 超时）
 
-### 安全过滤
+**安全过滤**
 
 `beforeSend` 钩子会自动剥离以下敏感 header：
 
@@ -68,7 +66,7 @@ bun run dev
 - `cookie`
 - `set-cookie`
 
-### 忽略的错误类型
+**忽略的错误类型**
 
 以下错误模式会被忽略，不会上报：
 
@@ -78,13 +76,13 @@ bun run dev
 | `AbortError` / `The user aborted a request` | 用户主动取消 |
 | `CancelError` | 交互式取消信号 |
 
-### 其他配置
+**其他配置**
 
 - **采样率**：`sampleRate: 1.0`（捕获全部错误事件）
 - **面包屑上限**：`maxBreadcrumbs: 20`（控制 payload 体积）
 - **性能事务**：已关闭（`beforeSendTransaction` 返回 `null`），仅上报错误
 
-## API
+### API
 
 | 函数 | 说明 |
 |---|---|
@@ -95,7 +93,7 @@ bun run dev
 | `closeSentry(timeoutMs?)` | 刷出队列并关闭客户端，进程退出时调用 |
 | `isSentryInitialized()` | 检查是否已初始化 |
 
-## 实现文件
+### 实现文件
 
 | 文件 | 说明 |
 |---|---|
@@ -104,3 +102,8 @@ bun run dev
 | `src/utils/errorLogSink.ts` | 错误日志 sink，集成 `captureException` |
 | `src/utils/gracefulShutdown.ts` | 优雅退出，调用 `closeSentry()` |
 | `src/entrypoints/init.ts` | 启动时调用 `initSentry()` |
+
+## 关联笔记
+
+- [[feature-flags]] - 构建时 Feature Flags（含监控相关 flags）
+- [[growthbook-adapter]] - GrowthBook 远程配置接入