sentry-browser-sdk

所有技能 > SDK 设置 > 浏览器 SDK

Sentry 浏览器 SDK

一个有主见的向导，可扫描你的项目，并引导你为浏览器 JavaScript 完成 Sentry 设置——适用于原生 JS、jQuery、静态网站、WordPress，以及任何没有专属框架 SDK 的 JS 项目。

适用场景

• 用户要求“将 Sentry 添加到网站”或为原生 JavaScript 设置 Sentry
• 用户想安装 @sentry/browser 或配置 Loader Script
• 用户使用 WordPress、Shopify、Squarespace 或静态 HTML 网站
• 用户希望在没有框架的情况下进行错误监控、追踪、会话回放或日志记录
• 不适用任何专属框架 SDK

注意： 以下 SDK 版本和 API 适用于 @sentry/browser ≥10.0.0。 实施前，请务必对照 docs.sentry.io/platforms/javascript/ 进行核实。

---

阶段 1：检测

关键——先检查框架。 专属框架 SDK 的覆盖范围显著更广，在继续使用 @sentry/browser 之前，必须优先推荐这些 SDK。

步骤 1A：检测框架（发现后重定向）

# Check for React
cat package.json 2>/dev/null | grep -E '"react"'

# Check for Next.js
cat package.json 2>/dev/null | grep '"next"'

# Check for Vue
cat package.json 2>/dev/null | grep '"vue"'

# Check for Angular
cat package.json 2>/dev/null | grep '"@angular/core"'

# Check for Svelte / SvelteKit
cat package.json 2>/dev/null | grep -E '"svelte"|"@sveltejs/kit"'

# Check for Remix
cat package.json 2>/dev/null | grep -E '"@remix-run/react"|"@remix-run/node"'

# Check for Nuxt
cat package.json 2>/dev/null | grep '"nuxt"'

# Check for Astro
cat package.json 2>/dev/null | grep '"astro"'

# Check for Ember
cat package.json 2>/dev/null | grep '"ember-source"'

# Check for Node.js server frameworks (wrong SDK entirely)
cat package.json 2>/dev/null | grep -E '"express"|"fastify"|"@nestjs/core"|"koa"'

如果检测到框架，请停止并重定向：

检测到的框架	重定向至
next	加载 sentry-nextjs-sdk 技能——请勿在此继续
react（不含 Next.js）	加载 sentry-react-sdk 技能——请勿在此继续
vue	建议使用 @sentry/vue——参见 docs.sentry.io/platforms/javascript/guides/vue/
@angular/core	建议使用 @sentry/angular——参见 docs.sentry.io/platforms/javascript/guides/angular/
@sveltejs/kit	加载 sentry-svelte-sdk 技能——请勿在此继续
svelte（SPA，无 kit）	建议使用 @sentry/svelte——参见 docs.sentry.io/platforms/javascript/guides/svelte/
@remix-run	建议使用 @sentry/remix——参见 docs.sentry.io/platforms/javascript/guides/remix/
nuxt	建议使用 @sentry/nuxt——参见 docs.sentry.io/platforms/javascript/guides/nuxt/
astro	建议使用 @sentry/astro——参见 docs.sentry.io/platforms/javascript/guides/astro/
ember-source	建议使用 @sentry/ember——参见 docs.sentry.io/platforms/javascript/guides/ember/
express / fastify / @nestjs/core	这是一个 Node.js 服务端项目——加载 sentry-node-sdk 或 sentry-nestjs-sdk 技能

重定向的重要性： 框架 SDK 可提供路由器感知事务、错误边界、组件跟踪，通常还支持 SSR。直接在 React 或 Next.js 应用中使用 @sentry/browser 会失去所有这些功能。

只有在未检测到任何框架时，才继续使用 @sentry/browser。

步骤 1B：检测安装方式

# Check if there's a package.json at all (bundler environment)
ls package.json 2>/dev/null

# Check package manager
ls package-lock.json yarn.lock pnpm-lock.yaml bun.lockb 2>/dev/null

# Check build tool
ls vite.config.ts vite.config.js webpack.config.js rollup.config.js esbuild.config.js 2>/dev/null
cat package.json 2>/dev/null | grep -E '"vite"|"webpack"|"rollup"|"esbuild"'

# Check for CMS or static site indicators
ls wp-config.php wp-content/ 2>/dev/null   # WordPress
ls _config.yml _config.yaml 2>/dev/null    # Jekyll
ls config.toml 2>/dev/null                 # Hugo
ls .eleventy.js 2>/dev/null                # Eleventy

# Check for existing Sentry
cat package.json 2>/dev/null | grep '"@sentry/'
grep -r "sentry-cdn.com\|js.sentry-cdn.com" . --include="*.html" -l 2>/dev/null | head -3

需要确定的事项：

问题	影响
是否存在 package.json 和打包工具？	→ 路径 A：npm 安装
是否使用 WordPress、Shopify、静态 HTML，且没有 npm？	→ 路径 B：Loader Script
是否仅使用 script 标签，且无法使用 Loader Script？	→ 路径 C：CDN bundle
是否已经安装 @sentry/browser？	跳过安装，直接配置功能
构建工具是否为 Vite / webpack / Rollup / esbuild？	需配置 Source Maps 插件

---

阶段 2：提出建议

根据你的发现提出建议。先给出具体方案，不要提出开放式问题。

推荐（核心覆盖）：

• ✅ 错误监控 — 始终启用；捕获未处理的错误和 Promise 拒绝
• ✅ 追踪 — 推荐用于任何交互式网站；追踪页面加载和用户交互
• ✅ 会话回放 — 推荐用于面向用户的应用；记录错误发生前后的会话

可选（增强可观测性）：

• ⚡ 用户反馈 — 出错后直接收集用户报告
• ⚡ 日志记录 — 通过 Sentry.logger.* 记录结构化日志；需要 npm 或 CDN 日志包（Loader Script 不支持）
• ⚡ 性能分析 — JS 自分析 API；处于 beta 阶段，仅支持 Chromium，且需要 Document-Policy: js-profiling 响应头

功能推荐逻辑：

功能	推荐条件……
错误监控	始终 — 不可妥协的基准功能
追踪	始终用于交互式页面 — 页面加载和导航跨度价值很高
会话回放	面向用户的应用、支持流程或结账页面
用户反馈	以支持为重点的应用；希望通过应用内错误报告和截图收集反馈
日志记录	需要结构化日志搜索或日志与追踪的关联；仅适用于 npm 路径
性能分析	对性能要求高且仅面向 Chromium 的应用；需要 Document-Policy: js-profiling 响应头

安装路径建议：

场景	推荐路径
项目有 package.json 和打包工具	路径 A（npm） — 功能完整，支持源映射和摇树优化
WordPress、Shopify、Squarespace、静态 HTML	路径 B（Loader Script） — 无需构建工具，始终保持最新
无法使用 Loader Script 的静态 HTML	路径 C（CDN bundle） — 手动添加 <script> 标签

建议：“我推荐使用路径 A（npm）设置错误监控 + 追踪 + 会话回放。要我也添加日志记录或用户反馈吗？”

---

阶段 3：指导

路径 A：npm / yarn / pnpm（推荐 — 打包工具项目）

安装

npm install @sentry/browser --save
# or
yarn add @sentry/browser
# or
pnpm add @sentry/browser

创建 src/instrument.ts

Sentry 必须在任何其他代码运行之前初始化。将 Sentry.init() 放在专用的旁加载文件中：

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

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN, // Adjust per build tool (see table below)
  environment: import.meta.env.MODE,
  release: import.meta.env.VITE_APP_VERSION, // inject at build time

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },

  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],

  // Tracing
  tracesSampleRate: 1.0, // lower to 0.1–0.2 in production
  tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],

  // Session Replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  enableLogs: true,
});

按构建工具设置 DSN 环境变量：

构建工具	变量名称	在代码中的访问方式
Vite	VITE_SENTRY_DSN	import.meta.env.VITE_SENTRY_DSN
自定义 webpack	SENTRY_DSN	process.env.SENTRY_DSN
esbuild	SENTRY_DSN	process.env.SENTRY_DSN
Rollup	SENTRY_DSN	process.env.SENTRY_DSN

入口点设置

在入口文件中，将 instrument.ts 作为第一个导入项导入：

// src/main.ts or src/index.ts
import "./instrument";  // ← MUST be first

// ... rest of your app

设置源映射（强烈推荐）

没有源映射时，堆栈跟踪会显示压缩后的代码。设置构建插件以自动上传源映射：

没有专用的浏览器向导： 没有 npx @sentry/wizard -i browser 这个标志。最接近的是 npx @sentry/wizard@latest -i sourcemaps，它只会为已初始化的 SDK 配置源映射上传。

Vite（vite.config.ts）：

import { defineConfig } from "vite";
import { sentryVitePlugin } from "@sentry/vite-plugin";

export default defineConfig({
  build: { sourcemap: "hidden" },
  plugins: [
    // sentryVitePlugin MUST be last
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

webpack（webpack.config.js）：

const { sentryWebpackPlugin } = require("@sentry/webpack-plugin");

module.exports = {
  devtool: "hidden-source-map",
  plugins: [
    sentryWebpackPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
};

Rollup（rollup.config.js）：

import { sentryRollupPlugin } from "@sentry/rollup-plugin";

export default {
  output: { sourcemap: "hidden" },
  plugins: [
    sentryRollupPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
};

esbuild（build.js）：

const { sentryEsbuildPlugin } = require("@sentry/esbuild-plugin");

require("esbuild").build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  sourcemap: "hidden",
  plugins: [
    sentryEsbuildPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

⚠️ esbuild 插件不完全支持 splitting: true。如果启用了代码拆分，请改用 sentry-cli。

使用 sentry-cli（适用于任何工具链 / CI）：

# After your build step:
npx @sentry/cli sourcemaps inject ./dist
npx @sentry/cli sourcemaps upload ./dist

添加用于身份验证的 .env（切勿提交）：

SENTRY_AUTH_TOKEN=sntrys_...
SENTRY_ORG=my-org-slug
SENTRY_PROJECT=my-project-slug

路径 B：Loader Script（WordPress、静态网站、Shopify、Squarespace）

适用场景： 没有构建系统的网站。Loader Script 是一个单独的 <script> 标签，可按需加载完整 SDK，通过 Sentry 的 CDN 始终保持最新版本，并在 SDK 加载前缓冲错误。

获取 Loader Script： Sentry UI → Settings → Projects →（你的项目）→ SDK Setup → Loader Script

复制生成的标签，并将其放在每个页面的第一个脚本位置：

<!DOCTYPE html>
<html>
  <head>
    
    <script>
      window.sentryOnLoad = function () {
        Sentry.init({
          // DSN is already configured in the loader URL
          tracesSampleRate: 1.0,
          replaysSessionSampleRate: 0.1,
          replaysOnErrorSampleRate: 1.0,
        });
      };
    </script>

    
    <script
      src="https://js.sentry-cdn.com/YOUR_PUBLIC_KEY.min.js"
      crossorigin="anonymous"
    ></script>
  </head>
  ...
</html>

Loader 加载模式：

模式	操作	SDK 加载时机
Lazy（默认）	无需额外操作	首次发生错误或手动调用 Sentry 时
Eager	在 <script> 中添加 data-lazy="no"	页面中的所有脚本执行完毕后
Manual	调用 Sentry.forceLoad()	调用该方法时

SDK 加载前可安全调用（调用会被缓冲）：

• Sentry.captureException()
• Sentry.captureMessage()
• Sentry.captureEvent()
• Sentry.addBreadcrumb()
• Sentry.withScope()

对于其他方法，请使用 Sentry.onLoad()：

<script>
  window.Sentry && Sentry.onLoad(function () {
    Sentry.setUser({ id: "123" });
  });
</script>

通过全局变量设置 release（可选）：

<script>
  window.SENTRY_RELEASE = { id: "[email protected]" };
</script>

Loader Script 的限制：

• ❌ 不支持 Sentry.logger.*（日志记录）——仅 npm 路径支持
• ❌ 不支持框架专属功能（React ErrorBoundary、Vue Router 跟踪等）
• ❌ 只有 SDK 加载后发起的 fetch 调用才会添加跟踪标头
• ❌ 版本更改需要几分钟才能通过 CDN 缓存传播
• ⚠️ 使用 Loader 时，所有其他脚本都应使用 defer（而非 async）

CSP 要求：

script-src: https://browser.sentry-cdn.com https://js.sentry-cdn.com
connect-src: *.sentry.io

---

路径 C：CDN Bundle（手动添加脚本标签）

适用场景： 无法使用 Loader Script，但需要同步加载的页面。

选择符合功能需求的 Bundle，并将其放在所有其他脚本之前：

仅错误（占用空间最小）：

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.min.js"
  integrity="sha384-L/HYBH2QCeLyXhcZ0hPTxWMnyMJburPJyVoBmRk4OoilqrOWq5kU4PNTLFYrCYPr"
  crossorigin="anonymous"
></script>

错误 + 跟踪：

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.min.js"
  integrity="sha384-DIqcfVcfIewrWiNWfVZcGWExO5v673hkkC5ixJnmAprAfJajpUDEAL35QgkOB5gw"
  crossorigin="anonymous"
></script>

错误 + 会话回放：

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.replay.min.js"
  integrity="sha384-sbojwIJFpv9duIzsI9FRm87g7pB15s4QwJS1m1xMSOdV1CF3pwgrPPEu38Em7M9+"
  crossorigin="anonymous"
></script>

错误 + 跟踪 + 回放（推荐的完整配置）：

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.min.js"
  integrity="sha384-oo2U4zsTxaHSPXJEnXtaQPeS4Z/qbTqoBL9xFgGxvjJHKQjIrB+VRlu97/iXBtzw"
  crossorigin="anonymous"
></script>

错误 + 跟踪 + 回放 + 用户反馈：

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.feedback.min.js"
  integrity="sha384-SmHU39Qs9cua0KLtq3A6gis1/cqM1nZ6fnGzlvWAPiwhBDO5SmwFQV65BBpJnB3n"
  crossorigin="anonymous"
></script>

完整 Bundle（包含所有功能）：

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.feedback.logs.metrics.min.js"
  integrity="sha384-gOjSzRxwpXpy0FlT6lg/AVhagqrsUrOWUO7jm6TJwuZ9YVHtYK0MBA2hW2FGrIGl"
  crossorigin="anonymous"
></script>

CDN Bundle 变体摘要：

Bundle	功能	适用场景
bundle.min.js	仅错误	占用空间尽可能小
bundle.tracing.min.js	+ 跟踪	性能监控
bundle.replay.min.js	+ 回放	会话录制
bundle.tracing.replay.min.js	+ 跟踪 + 回放	完整可观测性
bundle.tracing.replay.feedback.min.js	+ 用户反馈	+ 应用内反馈组件
bundle.logs.metrics.min.js	+ 日志 + 指标	结构化日志（CDN）
bundle.tracing.replay.feedback.logs.metrics.min.js	所有功能	覆盖范围最大

在脚本标签后初始化：

<script>
  Sentry.init({
    dsn: "https://[email protected]/YOUR_PROJECT",
    environment: "production",
    release: "[email protected]",
    integrations: [
      Sentry.browserTracingIntegration(),
      Sentry.replayIntegration({
        maskAllText: true,
        blockAllMedia: true,
      }),
    ],
    tracesSampleRate: 1.0,
    tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],
    replaysSessionSampleRate: 0.1,
    replaysOnErrorSampleRate: 1.0,
  });
</script>

CDN 的 CSP 要求：

script-src: https://browser.sentry-cdn.com https://js.sentry-cdn.com
connect-src: *.sentry.io

---

各项约定功能

逐项配置功能。加载参考文件，按步骤操作，并在继续之前进行验证：

功能	参考文件	在以下情况下加载……
错误监控	${SKILL_ROOT}/references/error-monitoring.md	始终（基线配置）
跟踪	${SKILL_ROOT}/references/tracing.md	跟踪页面加载/API 调用
会话回放	${SKILL_ROOT}/references/session-replay.md	面向用户的应用
日志记录	${SKILL_ROOT}/references/logging.md	搜索结构化日志；使用 npm 或 CDN 日志 Bundle（不支持 Loader Script）
性能分析	${SKILL_ROOT}/references/profiling.md	性能关键场景，仅限 Chromium
用户反馈	${SKILL_ROOT}/references/user-feedback.md	在发生错误后收集用户报告

对于每项功能：Read ${SKILL_ROOT}/references/<feature>.md，严格按照步骤操作，并验证其是否正常工作。

---

配置参考

Sentry.init() 的关键选项

选项	类型	默认值	说明
dsn	string	—	必填。 为空时 SDK 将被禁用
environment	string	"production"	例如："staging"、"development"
release	string	—	例如："[email protected]" 或 git SHA — 将错误关联到发布版本
sendDefaultPii	boolean	false	包含 IP 地址和请求标头。将在 v11 中弃用 — 请改用 dataCollection
dataCollection	object	—	对收集的数据进行精细控制（v10.54+）。请参阅下表
tracesSampleRate	number	—	0–1；开发环境使用 1.0，生产环境使用 0.1–0.2
tracesSampler	function	—	按事务采样；优先于采样率
tracePropagationTargets	(string|RegExp)[]	同源	接收分布式追踪标头的出站 URL
replaysSessionSampleRate	number	—	记录的所有会话所占比例
replaysOnErrorSampleRate	number	—	记录的错误会话所占比例
enableLogs	boolean	false	启用 Sentry.logger.* API（npm 或 CDN 日志包；不适用于 Loader Script）
attachStackTrace	boolean	false	在 captureMessage() 调用中附加堆栈追踪
maxBreadcrumbs	number	100	每个事件存储的面包屑数量
debug	boolean	false	在控制台输出详细的 SDK 信息
tunnel	string	—	用于绕过广告拦截器的代理 URL
ignoreErrors	(string|RegExp)[]	[]	丢弃与这些模式匹配的错误
denyUrls	(string|RegExp)[]	[]	丢弃来自这些 URL 中脚本的错误
allowUrls	(string|RegExp)[]	[]	仅捕获来自这些脚本 URL 的错误
spotlight	boolean|string	false	将事件转发到 Spotlight 本地开发叠加层

浏览器专用选项

选项	类型	默认值	说明
cdnBaseUrl	string	—	用于延迟加载集成的基础 URL
skipBrowserExtensionCheck	boolean	false	跳过浏览器扩展上下文检查

dataCollection 选项（v10.54+）

对 SDK 收集的数据进行精细控制。用粒度更细的设置取代简单的 sendDefaultPii 布尔值。省略此选项时，为保持向后兼容，将回退到 sendDefaultPii。

字段	类型	默认值	说明
userInfo	boolean	true	根据插桩自动填充 user.* 字段
cookies	boolean | { allow: string[] } | { deny: string[] }	true	Cookie 收集；true = 全部收集（经过筛选），false = 不收集，allow/deny = 指定键
httpHeaders	{ request?, response? }	{ request: true, response: true }	HTTP 标头收集；每项可以是 boolean 或 allow/deny 对象
httpBodies	string[]	["incomingRequest", "outgoingRequest", "incomingResponse", "outgoingResponse"]	要收集的 HTTP 正文类型（显式设置 dataCollection 时）
queryParams	boolean | { allow: string[] } | { deny: string[] }	true	收集查询参数并筛选敏感值
genAI	{ inputs?, outputs? }	{ inputs: true, outputs: true }	记录生成式 AI 的输入和输出
stackFrameVariables	boolean	true	捕获堆栈帧中的局部变量值
frameContextLines	number	5	堆栈帧周围的源代码上下文行数

示例：

Sentry.init({
  dsn: "...",
  dataCollection: {
    userInfo: true,
    cookies: { deny: ["session_id", "auth_token"] },
    httpHeaders: {
      request: { deny: ["authorization", "cookie"] },
      response: true,
    },
    queryParams: { allow: ["utm_source", "utm_campaign"] },
  },
});

window.SENTRY_RELEASE 全局变量（CDN / Loader Path）

在 SDK 加载前设置发布版本：

<script>
  window.SENTRY_RELEASE = { id: "[email protected]" };
</script>

---

验证

触发测试事件，确认 Sentry 正在接收数据：

npm / CDN 路径：

<button onclick="throw new Error('Sentry Browser Test Error')">
  Test Error
</button>

性能验证（npm 路径）：

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

Sentry.startSpan({ name: "Test Span", op: "test" }, () => {
  // your operation
});

手动捕获：

Sentry.captureException(new Error("Manual test"));
Sentry.captureMessage("Manual test message", "info");

检查 Sentry 控制面板：

• Issues → 几秒内即可看到错误
• Traces → 可看到页面加载事务
• Replays → 与页面交互后可看到会话录制
• Logs → 启用日志记录时可看到结构化日志条目（npm 或 CDN 日志 bundle）

如果没有任何显示，请在 Sentry.init() 中设置 debug: true，并检查浏览器控制台。

---

第 4 阶段：交叉关联

完成浏览器设置后，检查是否有配套后端尚未接入 Sentry：

ls ../backend ../server ../api ../go ../python 2>/dev/null
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3
cat ../pom.xml 2>/dev/null | grep '<artifactId>' | head -3
cat ../composer.json 2>/dev/null | head -3

如果存在尚未配置 Sentry 的后端，请建议使用相应的 skill：

检测到的后端	建议的 skill
Go（go.mod）	sentry-go-sdk
Python（requirements.txt、pyproject.toml）	sentry-python-sdk
Ruby（Gemfile）	sentry-ruby-sdk
PHP（composer.json）	sentry-php-sdk
.NET（*.csproj、*.sln）	sentry-dotnet-sdk
Java（pom.xml、build.gradle）	参阅 docs.sentry.io/platforms/java/
Node.js（Express、Fastify）	sentry-node-sdk
NestJS（@nestjs/core）	sentry-nestjs-sdk

---

故障排除

问题	解决方案
未显示事件	设置 debug: true，检查 DSN，并打开浏览器控制台查看 SDK 错误
Source map 无法正常工作	在生产模式下构建（npm run build）；确认已设置 SENTRY_AUTH_TOKEN
堆栈跟踪已压缩	Source map 未上传 — 检查构建插件配置；运行 npx @sentry/wizard@latest -i sourcemaps
找不到 CDN bundle	检查 URL 中的版本号；查看 browser.sentry-cdn.com 获取最新版本
SRI 完整性错误	哈希不匹配 — 从此 skill 重新复制完整的 <script> 标签，包括 integrity 属性
Loader Script 未触发	确认它是页面上的第一个 <script>；检查控制台中是否有 CSP 错误
Loader 的追踪无法正常工作	SDK 加载前发起的 Fetch 调用不会被追踪 — 使用 Sentry.onLoad() 包装较早发起的调用
未调用 sentryOnLoad	必须在 Loader <script> 标签之前定义 window.sentryOnLoad
日志不可用	Sentry.logger.* 需要使用 npm，或名称中包含 .logs. 的 CDN bundle — Loader Script 不支持此功能
性能分析无法正常工作	确认文档响应中包含 Document-Policy: js-profiling 标头；仅限 Chromium
广告拦截器丢弃事件	设置 tunnel: "/sentry-tunnel" 并添加服务端中继端点
未录制会话回放	确认 init 中包含 replayIntegration()；检查 replaysSessionSampleRate > 0
回放 CSP 错误	在 CSP 中添加 worker-src 'self' blob: 和 child-src 'self' blob:
tracePropagationTargets 不匹配	检查正则表达式转义；默认仅限同源
浏览器扩展阻止事件	添加 denyUrls: [/chrome-extension:\/\//] 以过滤扩展程序错误
事件量过高	在生产环境中降低 sampleRate（错误）和 tracesSampleRate，从 1.0 调低
部署后才上传 Source map	必须在错误发生之前上传 Source map — 将其集成到 CI/CD 中
esbuild 分割冲突	sentryEsbuildPlugin 不支持 splitting: true — 请改用 sentry-cli