Loader Script
了解 Sentry JavaScript 加载器脚本
加载器脚本是初始化 Sentry SDK 最简单的方法。加载器脚本还会自动保持您的 Sentry SDK 更新,并提供对不同 Sentry 功能的配置。
要使用加载器,请在 Sentry UI 中前往 设置 > 项目 > (选择项目)> 客户端密钥 (DSN),然后点击“配置”按钮。从“JavaScript 加载器”部分复制脚本标签,并将其作为页面上的第一个脚本包含。通过将其放在第一位,您可以捕获并缓冲来自后续脚本的事件,同时确保完整的 SDK 在所有其他脚本运行完毕后再加载。
<script
src="https://js.sentry-cdn.com/examplePublicKey.min.js"
crossorigin="anonymous"
></script>
默认情况下,追踪 (Tracing) 和会话回放 (Session Replay) 是启用的。
当使用加载器脚本时,为了确保压缩后的资产文件有正确的堆栈跟踪,您需要要么 将源映射公开托管,要么 将其上传到 Sentry。
加载器有几个配置选项:
- 要加载的 SDK 版本
- 使用追踪 (Tracing)
- 使用会话回放 (Session Replay)
- 显示调试日志
要配置版本,请使用“JavaScript 加载器”设置中的下拉菜单,该菜单位于您之前复制的脚本标签下方。
请注意,由于缓存的原因,这里所做的版本更改可能需要几分钟才能生效。
如果您仅使用加载器来捕获错误,加载器不会在以下情况发生之前加载完整的 SDK:
- 未处理的错误
- 未处理的 Promise 拒绝
- 调用
Sentry.captureException
- 调用
Sentry.captureMessage
- 调用
Sentry.captureEvent
一旦这些情况之一发生,加载器将缓冲该事件并立即从我们的 CDN 请求完整的 SDK。在请求发出和 SDK 初始化完成之间发生的任何事件也将被缓冲,并且所有缓冲的事件将在 SDK 完全初始化后发送到 Sentry。
或者,您可以设置加载器更早地请求完整 SDK:仍然在页面加载期间,但在页面上的其他 JavaScript 运行之后(换句话说,在后续的事件循环中)。为此,请在您的脚本标签中包含 data-lazy="no"
。
<script
src="https://js.sentry-cdn.com/examplePublicKey.min.js"
crossorigin="anonymous"
data-lazy="no"
></script>
最后,如果您希望自行控制加载时机,可以调用 Sentry.forceLoad()
。您可以在加载器运行后立即调用它(这与设置 data-lazy="no"
有相同的效果),也可以在第一次未处理错误、未处理的 Promise 拒绝或调用 Sentry.captureMessage
或 Sentry.captureEvent
时调用它(这与不调用它完全相同)。请注意,您不能将加载延迟到上述触发事件之后。
如果启用了追踪 (Tracing) 和/或会话回放 (Session Replay),SDK 将立即获取并初始化包,以确保在页面加载后能够捕获事务和/或回放。
虽然加载器脚本无需任何配置即可在您的应用程序中正常工作,但您仍然可以根据需要配置 SDK。
对于追踪 (Tracing),SDK 默认将以 tracesSampleRate: 1
初始化。这意味着 SDK 将捕获所有追踪。
对于会话回放 (Session Replay),默认值为 replaysSessionSampleRate: 0.1
和 replaysOnErrorSampleRate: 1
。这意味着回放将捕获所有包含错误的会话,并且仅捕获 10% 的普通会话。
您可以通过在页面中添加以下内容来配置发布版本:
<script>
window.SENTRY_RELEASE = {
id: "...",
};
</script>
加载器脚本始终包含带有默认配置(包括您的 DSN)的 Sentry.init
调用。如果您希望进一步 配置您的 SDK,可以通过定义 window.sentryOnLoad
函数来进行自定义初始化调用。在此函数中定义的内容将 总是 在调用任何其他 SDK 方法之前被调用。
请确保在添加加载器脚本 之前 定义此函数,以确保它能在正确的时间被调用:
<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,唯一的区别是配置是在加载器脚本加载后立即执行的。
<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 加载完成后调用。
// 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 进行错误和追踪,您可以使用以下包:
<script
src="https://browser.sentry-cdn.com/8.54.0/bundle.tracing.min.js"
integrity="sha384-FcOoWwGt3BRR7L4NFYD7vSSpgZy8+mIhMVjjlEL3G197+f2IzKTIZ71JnYqNJYCo"
crossorigin="anonymous"
></script>
要使用 Sentry 进行错误捕获、追踪以及 会话回放,您可以使用以下包:
<script
src="https://browser.sentry-cdn.com/8.54.0/bundle.tracing.replay.min.js"
integrity="sha384-K0NUbsLfm4LERusNssFeb7sO/Nl+TTWYzPsLdIoYNENze4TtUzPa242pNMKxgjnm"
crossorigin="anonymous"
></script>
要使用 Sentry 进行错误监控以及 会话回放,但 不包括追踪,您可以使用以下包:
<script
src="https://browser.sentry-cdn.com/8.54.0/bundle.replay.min.js"
integrity="sha384-1dsrYqa5gW838wdhf/G0JS4Uu8+7khq7JufIHwyjU7ZfbWQJpzsBsMpnnNxhUGmH"
crossorigin="anonymous"
></script>
如果您只使用 Sentry 进行错误监控,而不需要性能追踪或回放功能,您可以使用以下包:
<script
src="https://browser.sentry-cdn.com/8.54.0/bundle.min.js"
integrity="sha384-OOkJGcfpcHOW2qdROjcfMtqqMTrDnSBag7fGypKUDA4WxyB6mmS5cMzY9YBGcBvF"
crossorigin="anonymous"
></script>
一旦您在页面中包含了 Sentry SDK 包,您就可以在自己的包中使用 Sentry:
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.js
是RewriteFrames
集成,编译为 ES5 并已压缩,不包含调试日志bundle.tracing.es5.debug.min.js
是启用了追踪的@sentry/browser
,编译为 ES5 并已压缩,包含调试日志
File | Integrity Checksum |
---|---|
browserprofiling.debug.min.js | sha384-t5lqgW1e1TF6GvFCDJpBRWGyq5hnTAUyitSKwaX/Tf4Mx5qd1mNM6W+UHS1eel7U |
browserprofiling.js | sha384-PX+lwikNlRSYE2GPA27dwg5BzkJff2rg8H9TL+qTA7cTAemLezghtWUiovccyPU7 |
browserprofiling.min.js | sha384-lNN8bz22Wnmv5oWyq9wauOOn/qEjTp+71ahgkwfWQKwoVFBoGDYWWyB4E9E5S42Q |
bundle.debug.min.js | sha384-B/i9mWooO0id+vk310ye5X6oKpr+Jjp9val0mlypuMY13P2FdRoxnJRSUAUgXhQn |
bundle.feedback.debug.min.js | sha384-yQzfDsZQW6k9zpF1i4RHs2EM66qk9ozEOMS7s8Wd5M0noeBZt3y4WnShiAHT2j67 |
bundle.feedback.js | sha384-4kdnqd44rRY2vc8TIHHF8GEE7kh7lVPJPjtWxI8mYUu+m/AR9G0lnmnvyYYwyomR |
bundle.feedback.min.js | sha384-bdF+q/SefES1kCntjuGocmo+FhYU4uf6rurEDmUuldIwonJ0Ze2XrtXzh/cApFvr |
bundle.js | sha384-7BCAVHkNs/VqmP90lh3cg/CaJ+1uS98jcT6lHxf6mhk0Yv5Xb9nQU1R+EqZIzhnq |
bundle.min.js | sha384-OOkJGcfpcHOW2qdROjcfMtqqMTrDnSBag7fGypKUDA4WxyB6mmS5cMzY9YBGcBvF |
bundle.replay.debug.min.js | sha384-yIwAssehnW6HmBBFxAMHrD6r9o9Q5R7QodPqoE2PFp1eox6Dsh0z8duUBokHvZYo |
bundle.replay.js | sha384-aJ3WYgO6zzxNWakCNudESXC8YaVo83Q45gEDM+PtTFvNFxGtZgX75OqPeCbQFXol |
bundle.replay.min.js | sha384-1dsrYqa5gW838wdhf/G0JS4Uu8+7khq7JufIHwyjU7ZfbWQJpzsBsMpnnNxhUGmH |
bundle.tracing.debug.min.js | sha384-7I8WGSIFwmePMtP+PUL1OKF2l2LtSQsT/DHPYNOT4U/JBsRsvSqvtftD0DNWYF1q |
bundle.tracing.js | sha384-9GhciIYEIYXBmiP4NM0VeHXoTiLpg+mw2siSG/I1zUNFii/xnuynbnjhRoJxdnfg |
bundle.tracing.min.js | sha384-FcOoWwGt3BRR7L4NFYD7vSSpgZy8+mIhMVjjlEL3G197+f2IzKTIZ71JnYqNJYCo |
bundle.tracing.replay.debug.min.js | sha384-9OVoqVOdjBpcE4eE1VI880bH0hRLdNdo9d+l7Hmcnwqf/Wvie+VqV3f+NtcYZXhZ |
bundle.tracing.replay.feedback.debug.min.js | sha384-wfHvfUXX/Gz2gB59K1rwCPqZyM4JTZFpZRDbqTd39TaK6ukseSEz+6oxbDcBy9+X |
bundle.tracing.replay.feedback.js | sha384-qpw5P/Geqm781hKWOopYfhm98HqrlGuNnBWF0TUPqasmpMtINM+PdYzjFALLYDt0 |
bundle.tracing.replay.feedback.min.js | sha384-aNUE5rjATOTfMaX3r6V0p+hEE3m4vTWGPSimTkJPd/BUCVxHJVWatOVybGs5Likt |
bundle.tracing.replay.js | sha384-V9S6xqSqkzowvcVh7j6iZzEoqtFqxqVnnitwWN+yYBirCpukCk+LBI2NNVFC9w/Q |
bundle.tracing.replay.min.js | sha384-K0NUbsLfm4LERusNssFeb7sO/Nl+TTWYzPsLdIoYNENze4TtUzPa242pNMKxgjnm |
captureconsole.debug.min.js | sha384-z/o8ddCF9yIaVNqv0N3X7C7EmbbrtQWfngbQGfgaIvz5KD+2+FiZdDitU7fifpeH |
captureconsole.js | sha384-bqpSsNOSdrLoEmMhVqWVhZKYUuosp64wDZsD0q/FHA6khqDbMhW5FYXxMaRFPA5W |
captureconsole.min.js | sha384-0J6O04K15U/JK9yWgp2HxDYCLLlxn+gnEO9GJR0JWEQx99Ih0A6/kLbd7vObNMZd |
contextlines.debug.min.js | sha384-xm1u/UABsXOvJl/v6mNv2H+/XynpvWvVR9D9bEXX/jFEGuKa1JAbnMjQZl+GCYww |
contextlines.js | sha384-Q6qm90VminsdfaWzIfCYaFvln5WpHFOS2rdQw+NNmE0ehO/YuUIfh+XOQIsft+qK |
contextlines.min.js | sha384-vO2GZLIP0T8sFX3/0NuDGos8nu9/EGfumwi0GPBgF5fgajv2hlDllFg0xok1T2fU |
debug.debug.min.js | sha384-2vQ8w7Nf14EYKgwpAoXrjT0itAQ21yQ2fgINg7mJp9hYBx+IOSrZgnGyEhXxXwAx |
debug.js | sha384-jRxdaiwoVIDTrdV/SAAJmN+7aDV7hgHjHUFYOgO9hbc0yNGJwmJ1pG99MOhC2qaC |
debug.min.js | sha384-Vk+1wlt43cH3JNPQxeG96J+V9BJUkafWofLXNDlgsDu6q9tgIfFKVFI1UPWfDYNW |
dedupe.debug.min.js | sha384-hBzhtbtZKBs7UKU7dAQfmMarGI7fdqeNi6/VX4p6NOQiCxN8M+xd4fs2t2yeKMtz |
dedupe.js | sha384-HSy3VEp2DH9g2ACGcTHdcMNC5eV089Jm+pvMfWoz5+4kjO8/URlAqa3OfVtHd597 |
dedupe.min.js | sha384-Wm7+DsXpZX4tqC5ub33ofpDnJbSAZPZm73zCWigQYlYEp5eJm+3CuXDwcWVXCyJr |
extraerrordata.debug.min.js | sha384-rdva/oaqAnNX4FdrJ4iCYoSkdVWlLjI4r6ArpZD6cyDFUwXhQlExJuOihtJCQovR |
extraerrordata.js | sha384-1MCR6ty2TlikokF8IE8/kfWsshRGMIKgx6oSYnAhIHHe/VCbXf+l2ReRXYBkUzA+ |
extraerrordata.min.js | sha384-QO805b5U1nqiiQEhLVPptEIFq1L6c8UgLcQLc20qI3GVytVIhq1m51G2F/gkf3ki |
feedback-modal.debug.min.js | sha384-3Efk1dOOXwDTAte6BBcPABq4O4AVGDXm/4lzZxpGY693R9Mh7ZplNB4HxT5KdmX8 |
feedback-modal.js | sha384-WHiUIpNiZSHcSGy61AsddptZlhSwb7ZatWwCdGhZ0tSPJokcdeGL5UtCDPJLIwos |
feedback-modal.min.js | sha384-MSGmdgV2Sjy2XAS6bmb6qbjc8s7y1FRWSjzdOjuVolevvRJe4GF8TMfRjyxYHYFZ |
feedback-screenshot.debug.min.js | sha384-cHCAc0mSH3QNsPguipJx93gW0etTVZnMZdwKsPY+bHc/No0CbXdavlJLxKEDUs47 |
feedback-screenshot.js | sha384-UA/zVFgj2psY/PBwQ+DX2tERFemyMj/IA08yzCDZA435li9KjR8264/znkMa+zwq |
feedback-screenshot.min.js | sha384-E2RBKJAMX2w2JsN15z36dTuzq7ZauAH63mVXTmPoV+ZdURfy9XSMPD1JOrt5p16M |
feedback.debug.min.js | sha384-eZZGUw+OBjS/pr/Rkb+oKK6cUo6Ek/HIYTrUgSAqQpjl7lseMYX9qn4qIetKo2+d |
feedback.js | sha384-ZgIaseEj+1661ciN6DeAxiXI8lkSZmMjvbpnXS0U9lpToGsdArvppLU9zEm6BQY3 |
feedback.min.js | sha384-Y5KOwU9DBg8MIgQXs5aap1f2VKsxYGUu7PZoVOyGvQIbm3L5aTRXDO31D4i1EPXL |
httpclient.debug.min.js | sha384-BsrXDAS07Yz+MaIZHa703S1qhQzMhA1B1NshJJf0WnHuB113VOAzyzv0xm5opBPe |
httpclient.js | sha384-vGgaugzsj4Bw7mboVXtxkqPvwrAJI5d5eTFWqz2AKLpyxP9JgJVn90BDHvMEGnkZ |
httpclient.min.js | sha384-IygjoSJFubUZz33mTb0HI2vd2hjEFrdY+ufrazGCYHg7vq68hKDJiB2h15KyHrMD |
modulemetadata.debug.min.js | sha384-Gc5QonluN3H8uRD+Mw+cvKcisBOhPP/77EtGDTE4RqpVBhyn0zJJ6QXmWlCRm8iT |
modulemetadata.js | sha384-hIVKgXnjCuJ3pJoTZbDDbnSHN/LUoDVwJyDY2NYb+AgKa//TyteNa0oHHC+GyZpv |
modulemetadata.min.js | sha384-i1e6lJFNTdyo12rTYcRnE44Hncu5/S0v/66vhMVtaNMIdpAxF4cXmzagOg5FxfIR |
multiplexedtransport.debug.min.js | sha384-FSuN6cRFObSZPTxGqZvOlbR3QQ8oTMyjU91HkfHaiQjGnvVPahm4IAKr+ToFo/jh |
multiplexedtransport.js | sha384-bDmIZYkln4/GHahtP1HzbodQtPzGwGKAOUtYO2We2k884tNUIBn5TgxQD+vkk+mn |
multiplexedtransport.min.js | sha384-aBDDTmXMd68ji1uSVlMY5OQXW7lr/obpkJ4IA9Jr6ovLtZ0pmt0rtTWHvx6ZasfT |
replay-canvas.debug.min.js | sha384-ZTJJ19KkmfpyD6CJWcwjZ0oxKzwO+WqmsfMtXgylpPjy6DMpV7cuDYZe7vubNk/7 |
replay-canvas.js | sha384-KuZ/JNgir8QUSidVB+4D6hA5MsrErvi9Q+UMywn0s4yVkFT3wCy3MOSRMCXgHKCZ |
replay-canvas.min.js | sha384-ItP2DAVqHhocqvtyjw0k25nr/KJuw7t6SI1e3rp2EQXpRV+UIjweKacC55BjMayP |
replay.debug.min.js | sha384-76l7vIB1e+opOYYsoyUKbtn+2MpQt00jaZUQQ8/FKnRDzYD/okknVdjxe5VEfOO/ |
replay.js | sha384-e+A0cefQOxu0N3g/R7dH6Jas3oAi87Zo8Vc2TWxcgKj2orkr2UHJF3KQ4/sM+tzu |
replay.min.js | sha384-CEHlTL+m3oTOJ+P2tsT+juzfE4PoNk7qVFLxgiAM5FeQwL3lTpvpetyb1WQVatcC |
reportingobserver.debug.min.js | sha384-eiRXrTDpnDJApp1eI8qKyCGRBXIJxdfa3mW4K/X5j8c69MgJG/e+YE/4hB3jKo5D |
reportingobserver.js | sha384-gGosBIqVMlqZ6uRUZemoWDYRRB6Xr5at2Mc929uKWH9LICwNHFKcvsLKrPQIMTXv |
reportingobserver.min.js | sha384-QCmy//ngPyEGnvxyb9Pm6/D91dMh2JMnA/UgskMC99De+CWRKRejDVJkpURDS9X+ |
rewriteframes.debug.min.js | sha384-aMhSCmOXv8HyeyyVpgQS1WsGXKubmz8TNU5UMISG87S5oz38G8/5xsdPVKaS4+Th |
rewriteframes.js | sha384-6E5TPLtHbboFATpYXOGHnaYgi10gkkvHU/iGiZC4HqPNdw9KxnWPP2p0dJmqteTu |
rewriteframes.min.js | sha384-b/BOjzBwa6mEoSQGHJG/2wK+DUcxpbgEyki9G06O8iBrfKgKdjxSyRfqvFKEI3xk |
sessiontiming.debug.min.js | sha384-tyXw2CIY0tcu9uA46gdI52M2jZ0r40x2dFQ2vyhpS3c08NuVAzlG3FPtgVTLwsnl |
sessiontiming.js | sha384-PY/thdc1lEnr2WRiBJ/UugbmBZ9hyQvVLYAp2XbLpIJiggNIk+vCTTmX/CvZnCae |
sessiontiming.min.js | sha384-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