Loader Script

了解 Sentry JavaScript 加载器脚本

加载器脚本是初始化 Sentry SDK 最简单的方法。加载器脚本还会自动保持您的 Sentry SDK 更新,并提供对不同 Sentry 功能的配置。

要使用加载器,请在 Sentry UI 中前往 设置 > 项目 > (选择项目)> 客户端密钥 (DSN),然后点击“配置”按钮。从“JavaScript 加载器”部分复制脚本标签,并将其作为页面上的第一个脚本包含。通过将其放在第一位,您可以捕获并缓冲来自后续脚本的事件,同时确保完整的 SDK 在所有其他脚本运行完毕后再加载。

Copied
<script
  src="https://js.sentry-cdn.com/examplePublicKey.min.js"
  crossorigin="anonymous"
></script>

默认情况下,追踪 (Tracing) 和会话回放 (Session Replay) 是启用的。

当使用加载器脚本时,为了确保压缩后的资产文件有正确的堆栈跟踪,您需要要么 将源映射公开托管,要么 将其上传到 Sentry

加载器有几个配置选项:

  • 要加载的 SDK 版本
  • 使用追踪 (Tracing)
  • 使用会话回放 (Session Replay)
  • 显示调试日志

要配置版本,请使用“JavaScript 加载器”设置中的下拉菜单,该菜单位于您之前复制的脚本标签下方。

JavaScript 加载器设置

请注意,由于缓存的原因,这里所做的版本更改可能需要几分钟才能生效。

如果您仅使用加载器来捕获错误,加载器不会在以下情况发生之前加载完整的 SDK:

  • 未处理的错误
  • 未处理的 Promise 拒绝
  • 调用 Sentry.captureException
  • 调用 Sentry.captureMessage
  • 调用 Sentry.captureEvent

一旦这些情况之一发生,加载器将缓冲该事件并立即从我们的 CDN 请求完整的 SDK。在请求发出和 SDK 初始化完成之间发生的任何事件也将被缓冲,并且所有缓冲的事件将在 SDK 完全初始化后发送到 Sentry。

或者,您可以设置加载器更早地请求完整 SDK:仍然在页面加载期间,但在页面上的其他 JavaScript 运行之后(换句话说,在后续的事件循环中)。为此,请在您的脚本标签中包含 data-lazy="no"

Copied
<script
  src="https://js.sentry-cdn.com/examplePublicKey.min.js"
  crossorigin="anonymous"
  data-lazy="no"
></script>

最后,如果您希望自行控制加载时机,可以调用 Sentry.forceLoad()。您可以在加载器运行后立即调用它(这与设置 data-lazy="no" 有相同的效果),也可以在第一次未处理错误、未处理的 Promise 拒绝或调用 Sentry.captureMessageSentry.captureEvent 时调用它(这与不调用它完全相同)。请注意,您不能将加载延迟到上述触发事件之后。

如果启用了追踪 (Tracing) 和/或会话回放 (Session Replay),SDK 将立即获取并初始化包,以确保在页面加载后能够捕获事务和/或回放。

虽然加载器脚本无需任何配置即可在您的应用程序中正常工作,但您仍然可以根据需要配置 SDK。

对于追踪 (Tracing),SDK 默认将以 tracesSampleRate: 1 初始化。这意味着 SDK 将捕获所有追踪。

对于会话回放 (Session Replay),默认值为 replaysSessionSampleRate: 0.1replaysOnErrorSampleRate: 1。这意味着回放将捕获所有包含错误的会话,并且仅捕获 10% 的普通会话。

您可以通过在页面中添加以下内容来配置发布版本:

Copied
<script>
  window.SENTRY_RELEASE = {
    id: "...",
  };
</script>

加载器脚本始终包含带有默认配置(包括您的 DSN)的 Sentry.init 调用。如果您希望进一步 配置您的 SDK,可以通过定义 window.sentryOnLoad 函数来进行自定义初始化调用。在此函数中定义的内容将 总是 在调用任何其他 SDK 方法之前被调用。

请确保在添加加载器脚本 之前 定义此函数,以确保它能在正确的时间被调用:

Copied
<script>
  // Configure sentryOnLoad before adding the Loader Script
  window.sentryOnLoad = function () {
    Sentry.init({
      // add custom config here
    });
  };
</script>

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

window.sentryOnLoad 函数内部,您可以配置自定义的 Sentry.init() 调用。您可以像使用 CDN 时一样精确地配置您的 SDK,唯一的区别是配置是在加载器脚本加载后立即执行的。

Copied
<script>
  // Configure sentryOnLoad before adding the Loader Script
  window.sentryOnLoad = function () {
    Sentry.init({
      release: " ... ",
      environment: " ... "
    });
    Sentry.setTag(...);
    // etc.
  };
</script>

默认情况下,加载器会确保您可以在任何时候直接在 Sentry 上调用以下函数,即使 SDK 尚未加载:

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

如果您需要在使用加载器时调用其他方法,则必须使用 Sentry.onLoad() 来保护这些调用。传递给 onLoad() 的任何回调函数将在以下两种情况下被调用:如果 SDK 已加载,则立即调用;否则,在 SDK 加载完成后调用。

Copied
// Guard against window.Sentry not being available, e.g. due to Ad-blockers
window.Sentry &&
  Sentry.onLoad(function () {
    // Inside of this callback,
    // we guarantee that `Sentry` is fully loaded and all APIs are available
    const client = Sentry.getClient();
    // do something custom here
  });

当仅使用加载器脚本捕获错误时,脚本会异步注入 SDK。这意味着只有 未处理的错误未处理的 Promise 拒绝 会在 SDK 完全加载之前被捕获并缓冲。具体来说,捕获 面包屑数据 的功能将在 SDK 完全加载和初始化后才可用。为了减少这些功能不可用的时间,您可以设置 data-lazy="no" 或调用 forceLoad(),如上所述。

如果您想了解加载器本身的内部工作原理,可以在 Sentry 仓库 中阅读详细的源代码。

Sentry 支持从 CDN 加载 JavaScript SDK。通常我们建议使用我们的加载器。如果您 必须 使用 CDN,请参阅下方的 可用包

要使用 Sentry 进行错误和追踪,您可以使用以下包:

Copied
<script
  src="https://browser.sentry-cdn.com/8.54.0/bundle.tracing.min.js"
  integrity="sha384-FcOoWwGt3BRR7L4NFYD7vSSpgZy8+mIhMVjjlEL3G197+f2IzKTIZ71JnYqNJYCo"
  crossorigin="anonymous"
></script>

要使用 Sentry 进行错误捕获、追踪以及 会话回放,您可以使用以下包:

Copied
<script
  src="https://browser.sentry-cdn.com/8.54.0/bundle.tracing.replay.min.js"
  integrity="sha384-K0NUbsLfm4LERusNssFeb7sO/Nl+TTWYzPsLdIoYNENze4TtUzPa242pNMKxgjnm"
  crossorigin="anonymous"
></script>

要使用 Sentry 进行错误监控以及 会话回放,但 不包括追踪,您可以使用以下包:

Copied
<script
  src="https://browser.sentry-cdn.com/8.54.0/bundle.replay.min.js"
  integrity="sha384-1dsrYqa5gW838wdhf/G0JS4Uu8+7khq7JufIHwyjU7ZfbWQJpzsBsMpnnNxhUGmH"
  crossorigin="anonymous"
></script>

如果您只使用 Sentry 进行错误监控,而不需要性能追踪或回放功能,您可以使用以下包:

Copied
<script
  src="https://browser.sentry-cdn.com/8.54.0/bundle.min.js"
  integrity="sha384-OOkJGcfpcHOW2qdROjcfMtqqMTrDnSBag7fGypKUDA4WxyB6mmS5cMzY9YBGcBvF"
  crossorigin="anonymous"
></script>

一旦您在页面中包含了 Sentry SDK 包,您就可以在自己的包中使用 Sentry:

Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  // this assumes your build process replaces `process.env.npm_package_version` with a value
  release: "my-project-name@" + process.env.npm_package_version,
  integrations: [
    // If you use a bundle with tracing enabled, add the BrowserTracing integration
    Sentry.browserTracingIntegration(),
    // If you use a bundle with session replay enabled, add the Replay integration
    Sentry.replayIntegration(),
  ],

  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,

  // Set `tracePropagationTargets` to control for which URLs distributed tracing should be enabled
  tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
});

我们的 CDN 托管了多种包:

  • 仅包含错误监控的 @sentry/browser(命名为 bundle.<modifiers>.js
  • 包含错误和追踪的 @sentry/browser(命名为 bundle.tracing.<modifiers>.js
  • 包含错误和会话回放的 @sentry/browser(命名为 bundle.replay.<modifiers>.js
  • 包含错误、追踪和会话回放的 @sentry/browser(命名为 bundle.tracing.replay.<modifiers>.js
  • @sentry/integrations 中的每个集成(命名为 <integration-name>.<modifiers>.js

每个包都提供 ES6 和 ES5 版本。自 SDK v7 起,默认提供 ES6 版本。要使用 ES5 包,请添加 .es5 修饰符。

每个版本有三种包类型:

  • 压缩版(.min
  • 未压缩版(无 .min),包含调试日志
  • 压缩版带调试日志(.debug.min

带有调试日志的包会输出更详细的日志消息,这对调试问题非常有帮助。确保 启用调试模式 以在控制台中查看调试消息。 未压缩和带调试日志的包比压缩版的包体积更大。

例如:

  • bundle.js@sentry/browser,编译为 ES6 但未压缩,并包含调试日志(所有未压缩包均如此)
  • rewriteframes.es5.min.jsRewriteFrames 集成,编译为 ES5 并已压缩,不包含调试日志
  • bundle.tracing.es5.debug.min.js 是启用了追踪的 @sentry/browser,编译为 ES5 并已压缩,包含调试日志
FileIntegrity Checksum
browserprofiling.debug.min.jssha384-t5lqgW1e1TF6GvFCDJpBRWGyq5hnTAUyitSKwaX/Tf4Mx5qd1mNM6W+UHS1eel7U
browserprofiling.jssha384-PX+lwikNlRSYE2GPA27dwg5BzkJff2rg8H9TL+qTA7cTAemLezghtWUiovccyPU7
browserprofiling.min.jssha384-lNN8bz22Wnmv5oWyq9wauOOn/qEjTp+71ahgkwfWQKwoVFBoGDYWWyB4E9E5S42Q
bundle.debug.min.jssha384-B/i9mWooO0id+vk310ye5X6oKpr+Jjp9val0mlypuMY13P2FdRoxnJRSUAUgXhQn
bundle.feedback.debug.min.jssha384-yQzfDsZQW6k9zpF1i4RHs2EM66qk9ozEOMS7s8Wd5M0noeBZt3y4WnShiAHT2j67
bundle.feedback.jssha384-4kdnqd44rRY2vc8TIHHF8GEE7kh7lVPJPjtWxI8mYUu+m/AR9G0lnmnvyYYwyomR
bundle.feedback.min.jssha384-bdF+q/SefES1kCntjuGocmo+FhYU4uf6rurEDmUuldIwonJ0Ze2XrtXzh/cApFvr
bundle.jssha384-7BCAVHkNs/VqmP90lh3cg/CaJ+1uS98jcT6lHxf6mhk0Yv5Xb9nQU1R+EqZIzhnq
bundle.min.jssha384-OOkJGcfpcHOW2qdROjcfMtqqMTrDnSBag7fGypKUDA4WxyB6mmS5cMzY9YBGcBvF
bundle.replay.debug.min.jssha384-yIwAssehnW6HmBBFxAMHrD6r9o9Q5R7QodPqoE2PFp1eox6Dsh0z8duUBokHvZYo
bundle.replay.jssha384-aJ3WYgO6zzxNWakCNudESXC8YaVo83Q45gEDM+PtTFvNFxGtZgX75OqPeCbQFXol
bundle.replay.min.jssha384-1dsrYqa5gW838wdhf/G0JS4Uu8+7khq7JufIHwyjU7ZfbWQJpzsBsMpnnNxhUGmH
bundle.tracing.debug.min.jssha384-7I8WGSIFwmePMtP+PUL1OKF2l2LtSQsT/DHPYNOT4U/JBsRsvSqvtftD0DNWYF1q
bundle.tracing.jssha384-9GhciIYEIYXBmiP4NM0VeHXoTiLpg+mw2siSG/I1zUNFii/xnuynbnjhRoJxdnfg
bundle.tracing.min.jssha384-FcOoWwGt3BRR7L4NFYD7vSSpgZy8+mIhMVjjlEL3G197+f2IzKTIZ71JnYqNJYCo
bundle.tracing.replay.debug.min.jssha384-9OVoqVOdjBpcE4eE1VI880bH0hRLdNdo9d+l7Hmcnwqf/Wvie+VqV3f+NtcYZXhZ
bundle.tracing.replay.feedback.debug.min.jssha384-wfHvfUXX/Gz2gB59K1rwCPqZyM4JTZFpZRDbqTd39TaK6ukseSEz+6oxbDcBy9+X
bundle.tracing.replay.feedback.jssha384-qpw5P/Geqm781hKWOopYfhm98HqrlGuNnBWF0TUPqasmpMtINM+PdYzjFALLYDt0
bundle.tracing.replay.feedback.min.jssha384-aNUE5rjATOTfMaX3r6V0p+hEE3m4vTWGPSimTkJPd/BUCVxHJVWatOVybGs5Likt
bundle.tracing.replay.jssha384-V9S6xqSqkzowvcVh7j6iZzEoqtFqxqVnnitwWN+yYBirCpukCk+LBI2NNVFC9w/Q
bundle.tracing.replay.min.jssha384-K0NUbsLfm4LERusNssFeb7sO/Nl+TTWYzPsLdIoYNENze4TtUzPa242pNMKxgjnm
captureconsole.debug.min.jssha384-z/o8ddCF9yIaVNqv0N3X7C7EmbbrtQWfngbQGfgaIvz5KD+2+FiZdDitU7fifpeH
captureconsole.jssha384-bqpSsNOSdrLoEmMhVqWVhZKYUuosp64wDZsD0q/FHA6khqDbMhW5FYXxMaRFPA5W
captureconsole.min.jssha384-0J6O04K15U/JK9yWgp2HxDYCLLlxn+gnEO9GJR0JWEQx99Ih0A6/kLbd7vObNMZd
contextlines.debug.min.jssha384-xm1u/UABsXOvJl/v6mNv2H+/XynpvWvVR9D9bEXX/jFEGuKa1JAbnMjQZl+GCYww
contextlines.jssha384-Q6qm90VminsdfaWzIfCYaFvln5WpHFOS2rdQw+NNmE0ehO/YuUIfh+XOQIsft+qK
contextlines.min.jssha384-vO2GZLIP0T8sFX3/0NuDGos8nu9/EGfumwi0GPBgF5fgajv2hlDllFg0xok1T2fU
debug.debug.min.jssha384-2vQ8w7Nf14EYKgwpAoXrjT0itAQ21yQ2fgINg7mJp9hYBx+IOSrZgnGyEhXxXwAx
debug.jssha384-jRxdaiwoVIDTrdV/SAAJmN+7aDV7hgHjHUFYOgO9hbc0yNGJwmJ1pG99MOhC2qaC
debug.min.jssha384-Vk+1wlt43cH3JNPQxeG96J+V9BJUkafWofLXNDlgsDu6q9tgIfFKVFI1UPWfDYNW
dedupe.debug.min.jssha384-hBzhtbtZKBs7UKU7dAQfmMarGI7fdqeNi6/VX4p6NOQiCxN8M+xd4fs2t2yeKMtz
dedupe.jssha384-HSy3VEp2DH9g2ACGcTHdcMNC5eV089Jm+pvMfWoz5+4kjO8/URlAqa3OfVtHd597
dedupe.min.jssha384-Wm7+DsXpZX4tqC5ub33ofpDnJbSAZPZm73zCWigQYlYEp5eJm+3CuXDwcWVXCyJr
extraerrordata.debug.min.jssha384-rdva/oaqAnNX4FdrJ4iCYoSkdVWlLjI4r6ArpZD6cyDFUwXhQlExJuOihtJCQovR
extraerrordata.jssha384-1MCR6ty2TlikokF8IE8/kfWsshRGMIKgx6oSYnAhIHHe/VCbXf+l2ReRXYBkUzA+
extraerrordata.min.jssha384-QO805b5U1nqiiQEhLVPptEIFq1L6c8UgLcQLc20qI3GVytVIhq1m51G2F/gkf3ki
feedback-modal.debug.min.jssha384-3Efk1dOOXwDTAte6BBcPABq4O4AVGDXm/4lzZxpGY693R9Mh7ZplNB4HxT5KdmX8
feedback-modal.jssha384-WHiUIpNiZSHcSGy61AsddptZlhSwb7ZatWwCdGhZ0tSPJokcdeGL5UtCDPJLIwos
feedback-modal.min.jssha384-MSGmdgV2Sjy2XAS6bmb6qbjc8s7y1FRWSjzdOjuVolevvRJe4GF8TMfRjyxYHYFZ
feedback-screenshot.debug.min.jssha384-cHCAc0mSH3QNsPguipJx93gW0etTVZnMZdwKsPY+bHc/No0CbXdavlJLxKEDUs47
feedback-screenshot.jssha384-UA/zVFgj2psY/PBwQ+DX2tERFemyMj/IA08yzCDZA435li9KjR8264/znkMa+zwq
feedback-screenshot.min.jssha384-E2RBKJAMX2w2JsN15z36dTuzq7ZauAH63mVXTmPoV+ZdURfy9XSMPD1JOrt5p16M
feedback.debug.min.jssha384-eZZGUw+OBjS/pr/Rkb+oKK6cUo6Ek/HIYTrUgSAqQpjl7lseMYX9qn4qIetKo2+d
feedback.jssha384-ZgIaseEj+1661ciN6DeAxiXI8lkSZmMjvbpnXS0U9lpToGsdArvppLU9zEm6BQY3
feedback.min.jssha384-Y5KOwU9DBg8MIgQXs5aap1f2VKsxYGUu7PZoVOyGvQIbm3L5aTRXDO31D4i1EPXL
httpclient.debug.min.jssha384-BsrXDAS07Yz+MaIZHa703S1qhQzMhA1B1NshJJf0WnHuB113VOAzyzv0xm5opBPe
httpclient.jssha384-vGgaugzsj4Bw7mboVXtxkqPvwrAJI5d5eTFWqz2AKLpyxP9JgJVn90BDHvMEGnkZ
httpclient.min.jssha384-IygjoSJFubUZz33mTb0HI2vd2hjEFrdY+ufrazGCYHg7vq68hKDJiB2h15KyHrMD
modulemetadata.debug.min.jssha384-Gc5QonluN3H8uRD+Mw+cvKcisBOhPP/77EtGDTE4RqpVBhyn0zJJ6QXmWlCRm8iT
modulemetadata.jssha384-hIVKgXnjCuJ3pJoTZbDDbnSHN/LUoDVwJyDY2NYb+AgKa//TyteNa0oHHC+GyZpv
modulemetadata.min.jssha384-i1e6lJFNTdyo12rTYcRnE44Hncu5/S0v/66vhMVtaNMIdpAxF4cXmzagOg5FxfIR
multiplexedtransport.debug.min.jssha384-FSuN6cRFObSZPTxGqZvOlbR3QQ8oTMyjU91HkfHaiQjGnvVPahm4IAKr+ToFo/jh
multiplexedtransport.jssha384-bDmIZYkln4/GHahtP1HzbodQtPzGwGKAOUtYO2We2k884tNUIBn5TgxQD+vkk+mn
multiplexedtransport.min.jssha384-aBDDTmXMd68ji1uSVlMY5OQXW7lr/obpkJ4IA9Jr6ovLtZ0pmt0rtTWHvx6ZasfT
replay-canvas.debug.min.jssha384-ZTJJ19KkmfpyD6CJWcwjZ0oxKzwO+WqmsfMtXgylpPjy6DMpV7cuDYZe7vubNk/7
replay-canvas.jssha384-KuZ/JNgir8QUSidVB+4D6hA5MsrErvi9Q+UMywn0s4yVkFT3wCy3MOSRMCXgHKCZ
replay-canvas.min.jssha384-ItP2DAVqHhocqvtyjw0k25nr/KJuw7t6SI1e3rp2EQXpRV+UIjweKacC55BjMayP
replay.debug.min.jssha384-76l7vIB1e+opOYYsoyUKbtn+2MpQt00jaZUQQ8/FKnRDzYD/okknVdjxe5VEfOO/
replay.jssha384-e+A0cefQOxu0N3g/R7dH6Jas3oAi87Zo8Vc2TWxcgKj2orkr2UHJF3KQ4/sM+tzu
replay.min.jssha384-CEHlTL+m3oTOJ+P2tsT+juzfE4PoNk7qVFLxgiAM5FeQwL3lTpvpetyb1WQVatcC
reportingobserver.debug.min.jssha384-eiRXrTDpnDJApp1eI8qKyCGRBXIJxdfa3mW4K/X5j8c69MgJG/e+YE/4hB3jKo5D
reportingobserver.jssha384-gGosBIqVMlqZ6uRUZemoWDYRRB6Xr5at2Mc929uKWH9LICwNHFKcvsLKrPQIMTXv
reportingobserver.min.jssha384-QCmy//ngPyEGnvxyb9Pm6/D91dMh2JMnA/UgskMC99De+CWRKRejDVJkpURDS9X+
rewriteframes.debug.min.jssha384-aMhSCmOXv8HyeyyVpgQS1WsGXKubmz8TNU5UMISG87S5oz38G8/5xsdPVKaS4+Th
rewriteframes.jssha384-6E5TPLtHbboFATpYXOGHnaYgi10gkkvHU/iGiZC4HqPNdw9KxnWPP2p0dJmqteTu
rewriteframes.min.jssha384-b/BOjzBwa6mEoSQGHJG/2wK+DUcxpbgEyki9G06O8iBrfKgKdjxSyRfqvFKEI3xk
sessiontiming.debug.min.jssha384-tyXw2CIY0tcu9uA46gdI52M2jZ0r40x2dFQ2vyhpS3c08NuVAzlG3FPtgVTLwsnl
sessiontiming.jssha384-PY/thdc1lEnr2WRiBJ/UugbmBZ9hyQvVLYAp2XbLpIJiggNIk+vCTTmX/CvZnCae
sessiontiming.min.jssha384-C++1qL2vU3lbYLxU6COf+eaaMTr7ySRvcRF65zj/7aem8UTbpwfz+Efq3nILmen5

要查找旧版本 SDK 的完整性哈希值,您可以查看我们的 Browser SDK 发布注册表 这里

如果您使用了 defer 脚本属性,我们强烈建议您将浏览器 SDK 的脚本标签放在第一位,并将所有其他脚本标记为 defer(但不要使用 async)。这将确保 Sentry SDK 在其他脚本之前执行。

如果不这样做,可能会导致在 Sentry 加载之前发生错误,这意味着您将无法捕获这些错误。

如果您在网站上设置了内容安全策略 (CSP),您需要添加加载 SDK 的来源以及 DSN 的来源到 script-src 中。例如:

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