企业官网建设流程全解析

• 可观测性

本文基于 Sentry JavaScript SDK 仓库中的 v8 变更日志 系统梳理 SDK 8.x 完整版本周期（8.0.0-rc 系列至 8.55.0）的演进脉络：8.0.0 的破坏性重构（OpenTelemetry 化、Hub 移除、类集成废弃）、版本支持范围、ESM 加载钩子的发展、各框架 SDK 的引入（NestJS、Nuxt、Solid、Cloudflare），以及 v8 周期内各关键版本新增的集成、配置选项与废弃项。读完后你可以快速判断项目应停留在 v8 的哪个版本，以及升级到 v9 前需要处理哪些已废弃 API。

1. v8 的生命周期状态：先读这一条

docs/changelog/v8.md 文件开头的官方声明是所有 v8 用户必须知道的前提：

Support for Sentry SDK v8 will be dropped soon. We recommend migrating to the latest version of the SDK.（v8 的支持将很快结束，建议迁移到最新版本。）

文档将 v8 到 v9 的迁移指向 v8 到 v9 迁移指南。因此这份 changelog 的定位是"冻结版本的历史档案"：v8 分支仍在接收维护性补丁（例如 8.55.0 中 AWS Lambda Layer 的更名），但所有新特性都只合入主线。理解这一点是阅读下文所有条目的基调。

2. 8.0.0 里程碑：v8 周期的架构定调

2.1 升级方式：migr8 codemod 与迁移指南

changelog 为 8.0.0 给出的升级路径是：

1. 阅读官方迁移指南，处理各平台的破坏性变更；
2. 运行自动化迁移工具：

npx @sentry/migr8@latest

v7 周期中除getCurrentHub()外的所有废弃 API 在 v8 中全部移除。仓库根目录的 MIGRATION.md 提供逐条变更的深入说明（v8 changelog 中多处链接到该文件）。

2.2 版本支持范围

这是决定"能否升级"的硬性事实，以 8.0.0 条目为准：

Node 端

• @sentry/node及所有基于 Node 的服务端 SDK（@sentry/nextjs、@sentry/remix等）要求Node.js 14.8.0 及以上；
• 基于 ESM 的 Node 应用需要Node.js 18.19.0 及以上（由 ESM 加载钩子支持决定）。

浏览器端（要求 ES2018+ 兼容浏览器）

演进过程可在 changelog 中追溯：8.0.0-alpha.4 阶段（#10911）先以 ES2017 目标弃用 IE11（当时最低要求 Chrome 58 等），8.0.0-beta.1 阶段收紧到 ES2018（Chrome 63 等），最终 8.0.0 定稿为上表。

2.3 被移除/不再发布的包

以下包自 v8 起停止发布，这是迁移时的必查项：

2.4 集成改为函数式：类集成全部移除

v8 最直观的代码级变化是集成从类变为函数，旧类导出被删除：

// old (v7) Sentry.init({ integrations: [new Sentry.BrowserTracing()], }); // new (v8) Sentry.init({ integrations: [Sentry.browserTracingIntegration()], });

仓库根目录的 MIGRATION.md 中 "Removal of class-based integrations" 一节列出了完整的类到函数映射。

2.5 服务端初始化顺序成为硬约束

8.0.0-alpha.1 条目记录了 v8 最大的底层改动：@sentry/node全面转向 OpenTelemetry（#10762）。其带来的直接后果：

• Express、Fastify、Koa、Nest.js 等框架的性能插桩开箱即用，autoDiscoverNodePerformanceMonitoringIntegrations()不再需要；
• 必须先require/import并调用Sentry.init()，再导入其他任何模块，否则第三方包无法被插桩：

const Sentry = require('@sentry/node'); Sentry.init({ dsn: '...', // ... other config here }); // now require other things below this! const http = require('http'); const express = require('express');

changelog 因此推荐把初始化放进独立文件（如instrumentation.js）并在入口文件最顶部导入。8.0.0 条目还明确建议为服务端 SDK（Node、Bun、Deno、Serverless）采用这种"独立初始化文件"模式。

2.6 其他 8.0.0 破坏性细节

• 移除transpileClientSDK（#11978）：因弃用 IE11，Next.js SDK 不再提供该选项，需要旧浏览器支持时自行配置 Webpack 转译；
• Serverless 不再默认携带性能集成（#11998）：为控制 Lambda 包体积，数据库等性能集成需手动加入Sentry.init（使用 Sentry AWS Lambda layer 时除外）；
• 移除 XHR transport（#10703，alpha.1 阶段）：浏览器默认改用基于 fetch 的传输，无 fetch 的环境需自行 polyfill 或提供自定义 transport；
• 移除startTransaction、span.startChild()：性能 API 全面重写为startSpan系列（对应仓库文档 v8 新性能 API 说明）；
• 移除 Transaction 概念（#11422）：span 与 transaction 的边界被拉平。

3. ESM 支持的演进：从 loader 钩子到registerEsmLoaderHooks

ESM 插桩是 v8 周期跨多个版本逐步打磨的一条主线，changelog 中可清晰看到四步演进：

1. 8.0.0-alpha.9（#11338）：服务端 SDK 首次附带 ESM 加载钩子，使用方式：

# For Node.js <= 18.18.2 node --experimental-loader=@sentry/node/hook your-app.js # For Node.js >= 18.19.0 node --import=@sentry/node/register your-app.js

当时上游存在 bug，官方声明会在 8 正式版前修复。

2. 8.0.0-beta.1（#11498）：钩子文件更名为loader/import，命令变为node --loader=@sentry/node/loader（Node ≤ 18.18.2）或node --import=@sentry/node/import（Node ≥ 18.19.0）。

3. 8.0.0-rc.2：Sentry.init()本身即可在被--import标志加载的模块中完成 ESM 补丁注册，官方注明仅支持 Node18.19.0及以上（以及20.6.0及以上）。

4. 8.3.0 与 8.5.0：免代码初始化。支持通过 Node 标志直接完成初始化，无需手写 init 文件：

# ESM SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 node --import=@sentry/node/init app.mjs # CommonJS SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 node --require=@sentry/node/init app.js

8.5.0 进一步增加@sentry/node/preload钩子（#12213）：先以node --require @sentry/node/preload ./app.js启动，之后可以在任意时机（包括异步获取 DSN 后）再调用Sentry.init()，解决了"无法在应用最开头初始化"的场景。

5. 8.8.0（#12388）：升级 OTEL 依赖并让 OTEL 使用import-in-the-middlev1.8.0，集中修复了一批 ESM 场景问题（多 loader 并存、date-fns重复命名空间导出、openai自引用导入、discord.js的ENOENT等）。

6. 8.14.0 / 8.20.0 / 8.29.0：Sentry.init新增registerEsmLoaderHooks选项，8.20.0 允许把该选项传给preloadOpenTelemetry自定义 preload 脚本；8.29.0 增加onlyIncludeInstrumentedModules: true选项，只对有插桩的模块做包装，减少干扰：

import * as Sentry from '@sentry/node'; Sentry.init({ dsn: '__PUBLIC_DSN__', registerEsmLoaderHooks: { onlyIncludeInstrumentedModules: true }, });

值得注意的是 8.41.0 的废弃预告：registerEsmLoaderHooks.include/exclude细粒度选项被废弃，官方明确onlyIncludeInstrumentedModules: true将成为下一个大版本的默认行为，且该选项不再接受细粒度配置。

4. 版本周期中的框架 SDK 引入时间线

v8 周期同时也是多个新框架 SDK 从 alpha 走到 beta 的周期，changelog 为每个节点都有明确标注：

其中 Nuxt SDK 的三次行为调整值得单独注意（均会导致初始化方式变化）：

• 8.35.0：默认改为 Rollup 插件在服务端入口外包裹动态import()，官方提示"不要再加--import标志，否则会重复初始化"；出问题时可设sentry: { dynamicImportForServerEntry: false }回退。
• 8.35.0：sourcemap 改为必须显式开启客户端 sourcemap（sourcemap: { client: true }），目的是防止 sourcemap 意外泄露到公网。
• 8.43.0：又改回必须用--import初始化服务端 SDK以获得完整功能（8.35.0 的动态import()默认方案对部分项目不适用）；无法使用该标志时可通过autoInjectServerSentry: 'top-level-import'（或'experimental_dynamic-import'）在nuxt.config.ts中启用注入，但存在追踪限制：

node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs

// nuxt.config.ts sentry: { autoInjectServerSentry: 'top-level-import', },

8.52.0 的 SolidStartwithSentry配置器（下节详述）延续了同一条"把服务端配置注入构建产物"的路线。

5. 关键版本的特性深读

5.1 8.55.0（v8 周期末版本）：Lambda Layer 更名

8.55.0 的"重要变更"对留在 v8 的 AWS Lambda 用户是关键信息：

TheSentryNodeServerlessSDKAWS Lambda Layer will stop receiving updates. If you intend to stay onv8and receive updates useSentryNodeServerlessSDKv8instead.

即原SentryNodeServerlessSDKlayer 停止更新，v8 用户需要切换到新 layer 名SentryNodeServerlessSDKv8才能继续获得更新。该版本的其他条目包括：新增 Statsig 浏览器特性旗标集成（flags/v8）、补齐vercelAIIntegration导出、Nuxt 模块新增enabled选项用于完全禁用 Sentry、Vue SDK 支持 Pinia v3、React SDK 修复懒加载路由/组件的追踪等。

5.2 8.52.0：SolidStart 的withSentry配置包装器

8.52.0 为 SolidStart 引入withSentry包装，sentrySolidStartVite插件由withSentry自动添加：

import { defineConfig } from '@solidjs/start/config'; import { withSentry } from '@sentry/solidstart'; export default defineConfig( withSentry( {/* Your SolidStart config options... */}, { // Options for setting up source maps org: process.env.SENTRY_ORG, project: process.env.SENTRY_PROJECT, authToken: process.env.SENTRY_AUTH_TOKEN, }, ), );

配合该变更：Sentry 服务端配置不再需要放进public目录，而是写入src/instrument.server.ts，构建后落在服务端产物中作为instrument.server.mjs。服务端 SDK 的安装有两个选项：

1. **（推荐）**给启动命令加--import标志（路径取决于你的服务端配置）：node --import ./.output/server/instrument.server.mjs .output/server/index.mjs
2. 设置autoInjectServerSentry: 'top-level-import'，把 Sentry 配置以顶层 import 注入服务端入口（存在追踪限制）：

withSentry( {/* Your SolidStart config options... */}, { // Optional: Install Sentry with a top-level import autoInjectServerSentry: 'top-level-import', }, );

在当前仓库主分支中，该配置器的实现位于 withSentry.ts，说明这一 API 在后续版本中被保留并继续演进。

5.3 8.51.0：Prisma v6 兼容逃生舱

8.51.0 为prismaIntegration增加prismaInstrumentation选项作为"所有 Prisma 版本的逃生舱"，接入 Prisma v6 的性能数据需要三步：

1. 安装@prisma/instrumentationv6；
2. 将其实例传入集成选项：

import { PrismaInstrumentation } from '@prisma/instrumentation'; Sentry.init({ integrations: [ prismaIntegration({ // Override the default instrumentation that Sentry uses prismaInstrumentation: new PrismaInstrumentation(), }), ], });

传入的实例会覆盖集成默认使用的插桩实例，而prismaIntegration仍负责处理各 Prisma 版本间的数据兼容性； 3. 从 Prisma schema 的 client generator 块中移除previewFeatures = ["tracing"]。

8.54.0 随后补了一条fix(node/v8): Add compatibility layer for Prisma v5，说明 v8 分支持续在做 Prisma 多版本兼容维护。从当前仓库主分支的源码看，Prisma 集成现在实现于 prisma/index.ts，通过向globalThis.PRISMA_INSTRUMENTATION注册 tracing helper 直接兼容 Prisma v6/v7——也就是说 v8 中"逃生舱"要解决的版本错配问题，在后续大版本中已通过全局 helper 机制原生解决。

5.4 8.43.0：特性旗标（Feature Flags）三件套

8.43.0 一次性落地了三个特性旗标相关的浏览器集成，均用于把 flag 评估数据附加到后续错误事件：

import * as Sentry from '@sentry/browser'; Sentry.init({ integrations: [ // Track LaunchDarkly feature flags Sentry.launchDarklyIntegration(), // Track OpenFeature feature flags Sentry.openFeatureIntegration(), ], });

以及用于手动追踪任意 flag 的通用 API：

import * as Sentry from '@sentry/browser'; const featureFlagsIntegrationInstance = Sentry.featureFlagsIntegration(); Sentry.init({ integrations: [featureFlagsIntegrationInstance], }); // Manually track a feature flag featureFlagsIntegrationInstance.addFeatureFlag('my-feature', true);

当前主分支中这两个 SDK 集成的实现分别位于 launchdarkly 集成 与 openfeature 集成，8.55.0 还继续为 v8 分支追加了 Statsig 集成，可见特性旗标是贯穿整个 v8 周期后段的活跃方向。

5.5 8.36.0：SentryHttpInstrumentation与 Node HTTP 插桩重构

8.35.0 的条目解释了这次重构的动机：新增SentryHttpInstrumentation专门处理与 span 无关的 HTTP 插桩（请求/会话/作用域相关），与 OTel 的HttpInstrumentation并行运行，从而改善自定义 OTel 配置下的兼容性、避免双方插桩互相冲突。同时httpIntegration重新引入spans: false选项：关闭 span 发射但仍允许用户自定义HttpInstrumentation（httpIntegration({ spans: false })）。

同版本还有一项浏览器端行为变更：流（stream）插桩改为默认关闭，新增trackFetchStreamPerformance选项，设为true时 Sentry 才对 fetch 流做插桩。

5.6 8.26.0 与 8.30.0/8.31.0/8.38.0：Node 集成全家桶

v8 周期后段 Node 端持续扩充开箱集成，changelog 中有明确标注的主要节点：

fsIntegration在 8.26.0 中的配置示例（含两个风险相关的选项）：

Sentry.init({ integrations: [ Sentry.fsIntegration({ recordFilePaths: true, recordErrorMessagesAsSpanAttributes: true, }), ], });

在当前主分支中，fsIntegration实现位于 node/src/integrations/fs，kafkajs/amqplib/dataloader等则集中在 server-utils/src/integrations，可据此继续深入阅读具体插桩逻辑。

5.7 8.16.0：Next.js App Router 事务模型切换

8.16.0（#12729）是 Next.js 用户必读的条目：App Router 场景下，SDK 从"为每个顶层 Server Component 单独记录事务"切换为把整个请求捕获为单一事务（如GET /path/to/route），Server Component 的 span 作为其子 span。收益是：trace 有根 span、客户端数据流的耗时不再丢失；代价是 Sentry 中事务数量变少、span 变多（对 SaaS 配额消耗有相应影响）。Edge runtime 不受影响，仍按旧方式发事务。

5.8 8.12.0 与 8.11.0：核心 API 的两个小升级

• Sentry.init()直接返回 client（#12585），不再需要再调getClient()：

const client = Sentry.init();

• startSpan*系列新增parentSpan选项（#12567），可以显式指定 span 的父级：

Sentry.startSpan({ name: 'root' }, parent => { const span = Sentry.startInactiveSpan({ name: 'xxx', parentSpan: parent }); Sentry.startSpan({ name: 'xxx', parentSpan: parent }, () => {}); Sentry.startSpanManual({ name: 'xxx', parentSpan: parent }, () => {}); });

• 同版本还有maxSpanWaitDuration配置项（#12610）：控制 SDK 等待父 span 结束的最长秒数，超时会清理无父 span 的孤儿 span 以防内存泄漏；如果你的应用有超长 span，需要把该值调大，否则 span 可能被过早丢弃。8.43.0 中还补了一个防护：fix(node): Guard against invalid maxSpanWaitDuration values。

5.9 8.6.0 与 8.16.0：NestJS 的监控能力

• 8.6.0 引入Sentry.reactErrorHandler，用于 React 19 的hydrateRoot回调（onUncaughtError/onCaughtError）：

import * as Sentry from '@sentry/react'; import { hydrateRoot } from 'react-dom/client'; ReactDOM.hydrateRoot( document.getElementById('root'), <React.StrictMode> <App /> </React.StrictMode>, { onUncaughtError: Sentry.reactErrorHandler(), onCaughtError: Sentry.reactErrorHandler((error, errorInfo) => { // optional callback if users want custom config. }), }, );

• 8.16.0 为@sentry/nestjs增加@SentryCron装饰器，在 cron 任务前后向 Sentry 发送 check-in：

import { Cron } from '@nestjs/schedule'; import { SentryCron, MonitorConfig } from '@sentry/nestjs'; import type { MonitorConfig } from '@sentry/types'; const monitorConfig: MonitorConfig = { schedule: { type: 'crontab', value: '* * * * *', }, checkinMargin: 2, // In minutes. Optional. maxRuntime: 10, // In minutes. Optional. timezone: 'America/Los_Angeles', // Optional. }; export class MyCronService { @Cron('* * * * *') @SentryCron('my-monitor-slug', monitorConfig) handleCron() { // Your cron job logic here } }

5.10 8.4.0：Next.js App Router 客户端页面加载追踪

8.4.0 在 Next.js14.3.0-canary.64及以上版本上，为 React Server Components 的客户端页面加载加入追踪，使Error: An error occurred in the Server Components render.这类之前"无从查因"的客户端错误可以回溯到具体的服务端组件错误。同版本还有 Angular 18 的正式支持。

6. 废弃（Deprecation）清单：v8 期间预告的下个大版本变化

v8 周期大量使用"先废弃、下个大版本移除"的策略，这些条目集中描述了v9 将发生什么，是评估升级成本的最高价值信息。按主题归类：

6.1 采样与追踪选项

• enableTracing废弃（8.18.0，#12897）：改用tracesSampleRate/tracesSampler；要禁用性能监控则直接移除这两个选项。
• undefined传参语义变更（8.41.0，#14450）：当前Sentry.init({ tracesSampleRate: undefined })因 key 存在反而启用追踪（不产生 span）；下个大版本将改为与"不传"一致（禁用追踪）。官方建议：若你依赖现状，显式设置tracesSampleRate: 0，该写法在 v9 中同样启用追踪。tracesSampler、enableTracing同理。
• beforeSendSpan返回null的警告（8.41.0，#14433）：目前返回null可丢弃单个 span，但这会在 trace 中制造"空洞"；下个大版本起该钩子只能变更 span、不能丢弃 span，8.41.0 起对丢 span 的用法发出警告；且根 span 也会开始传入该钩子。官方建议改为在集成/插桩层控制 span 的产生。

6.2 会话追踪

• autoSessionTracking废弃（8.44.0，#14640）：启用会话追踪的推荐方式是不再设置autoSessionTracking，浏览器环境确保加入browserSessionIntegration（该集成正是 8.43.0 新增），服务端确保加入httpIntegration；禁用会话追踪则移除browserSessionIntegration，或服务端将httpIntegration的trackIncomingRequestsAsSessions设为false（该选项 8.43.0 加入）。
• RequestSession相关 API 废弃（8.43.0，#14566）：这些 API 主要供内部使用，后续服务端 Release Health 能力改由集成管理，SDK 不再暴露RequestSession概念。

6.3 集成与包

• Metrics API 废弃（8.37.0，#14157）：Metrics beta 于 10 月 7 日结束，下个大版本将移除该 API；现有调用可继续工作，但发送的数据不再被 Sentry 处理。
• @sentry/utils废弃（8.41.0，#14431）：将并入@sentry/core，不再建议继续使用。
• debugIntegration与sessionTimingIntegration废弃（8.40.0，#14363）：记录出网事件改用 hooks（beforeSend、beforeSendTransaction）；会话时长数据改用Sentry.setContext()。
• Vue/Nuxt 追踪选项收口（8.41.0 #14385、8.42.0 #14530）：Vue SDK 中分散在四处（Sentry.init、tracingOptions、vueIntegration()及其tracingOptions）的追踪配置，最终只保留vueIntegration({ tracingOptions })一条路；Nuxt 侧相应废弃Sentry.init里的tracingOptions，改为在 vueIntegration 中配置：

// sentry.client.config.ts import * as Sentry from '@sentry/nuxt'; Sentry.init({ // ... integrations: [ Sentry.vueIntegration({ tracingOptions: { trackComponents: true, }, }), ], });

• NestJS 系列重命名/合并（8.40.0，#14323/#14371/#14374）：@WithSentry改为@SentryExceptionCaptured（纯重命名）；SentryTracingInterceptor、SentryService功能并入Sentry.init后废弃；SentryGlobalGenericFilter、SentryGlobalGraphQLFilter统一由SentryGlobalFilter替代（drop-in）；@sentry/node中的nestIntegration与setupNestErrorHandler废弃，官方推荐迁移到专门的@sentry/nestjs包。
• getDomElement废弃（8.48.0，#14799）：无替代方案，直接移除即可。
• SvelteKitfetchProxyScriptNonce废弃（8.51.0，#15011）。
• registerEsmLoaderHooks.include/exclude废弃（8.41.0，#14486）：见 3 节，改由onlyIncludeInstrumentedModules表达。
• 工具函数批量废弃（8.41.0）：arrayify、flatten、urlEncode、validSeverityLevels、getNumberOfUrlSegments、memoBuilder、BAGGAGE_HEADER_NAME、makeFifoCache、addRequestDataToEvent、extractRequestData等——这些主要针对"自建 SDK"的使用者。
• Next.jshideSourceMaps类型废弃（8.43.0，#14594）：该功能 v8 已移除但当时忘记废弃，v9 彻底清除。

7. 数据质量修复：升级后"数字会变"的两个版本

changelog 中有两条明确警告"升级后监控数据会发生变化"的修复，运维层面需要预期管理：

1. 8.28.0：LCP/FCP/FP 归一化逻辑移除（#13502）。此前 SDK 错误地处理了浏览器上报的原始值，导致上报的 LCP/FCP/FP小于真实测量值；升级到该版本后这三个指标会跳升，Web Vitals Insights 中的性能分数可能相应下降——这是纠错，不是劣化。
2. 8.36.0：Next.js/Cloudflare/Vercel Edge 性能监控切换 OTEL（#13889）。事务命名与 OTel 语义约定对齐，服务端 pages router 事务从/[param]/my/route变为GET /[param]/my/route，Sentry 中的事务名称会出现明显差异。

8. 版本时间线速查

以下是 v8 周期内值得记住的节点（完整逐版本条目以 docs/changelog/v8.md 为准）：

9. 实践建议：基于这份 changelog 的决策清单

1. 新项目：直接采用最新版 SDK 并遵循 v8 到 v9 迁移指南 中列出的目标 API，不要基于 v8 特有的过渡形态（如autoSessionTracking、enableTracing）搭建配置。
2. 必须留在 v8 的项目：固定使用 8.55.0；若使用 AWS Lambda layer，切换到SentryNodeServerlessSDKv8命名以继续获得更新；关注 8.28.0 与 8.36.0 两个"数据突变"版本，在升级窗口提前同步监控告警阈值。
3. 评估 v8 → v9 的改造项：优先核对第 6 节的废弃清单——采样选项（tracesSampleRate: 0显式化）、beforeSendSpan中丢 span 的用法、autoSessionTracking、Vue/Nuxt 追踪选项收口、NestJS 装饰器/过滤器重命名、以及是否仍在 import@sentry/utils。
4. ESM 项目：升级到 8.8.0+（OTEL +import-in-the-middlev1.8.0）以获得最完整的 ESM 修复集合；需要精细控制插桩范围时使用registerEsmLoaderHooks.onlyIncludeInstrumentedModules，并对 v9 的默认收紧行为做预案。

本文所有版本行为描述均来自 docs/changelog/v8.md 的对应版本条目；源码级佐证参考 MIGRATION.md、v8 新性能 API、Prisma 集成实现、fsIntegration 实现、LaunchDarkly 集成实现 与 SolidStart withSentry 实现。

• 可观测性