upgrade-browser-sdk-v6

将 Datadog Browser SDK 升级到 v6

从 v5 迁移到 v6 的系统指南。请按顺序完成步骤 1-6。每个步骤都包含一个用于查找受影响代码的搜索模式。

步骤 1：更新 SDK 版本

CDN 配置 — 更新脚本 src URL：

v5 模式	v6 替换项
datadoghq-browser-agent.com/us1/v5/datadog-rum.js	datadoghq-browser-agent.com/us1/v6/datadog-rum.js
datadoghq-browser-agent.com/us1/v5/datadog-logs.js	datadoghq-browser-agent.com/us1/v6/datadog-logs.js
datadoghq-browser-agent.com/us1/v5/datadog-rum-slim.js	datadoghq-browser-agent.com/us1/v6/datadog-rum-slim.js

将 us1 替换为你的站点：eu1、us3、us5、ap1、ap2。对于 US1-FED，模式中没有站点前缀：datadog-rum-v6.js、datadog-logs-v6.js、datadog-rum-slim-v6.js。

搜索：grep -r "datadoghq-browser-agent.com.*v5" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"

npm 配置 — 更新 package.json 依赖：

"@datadog/browser-rum": "^6.0.0"
"@datadog/browser-logs": "^6.0.0"
"@datadog/browser-rum-slim": "^6.0.0"

然后运行你的包管理器（npm install、yarn install 等）并重新构建。

如果使用了框架集成，也请将其升级到 v6：@datadog/browser-rum-react。

搜索：grep -r "@datadog/browser-" --include="package.json" .

步骤 2：移除已弃用的选项

从 Core 中移除（影响 RUM 和 Logs）

选项	操作
useCrossSiteSessionCookie	替换为 usePartitionedCrossSiteSessionCookie。

从 Logs 中移除

选项	操作
sendLogsAfterSessionExpiration	删除。在 v6 中，会话过期后始终会发送日志（不带会话 ID）。不再需要此选项。

搜索：grep -rn 'useCrossSiteSessionCookie\|sendLogsAfterSessionExpiration' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

步骤 3：更新已更改的默认值

v6 更改了若干默认行为。请逐项检查，并在需要时进行调整：

3a. trackUserInteractions、trackResources 和 trackLongTasks 默认值为 true

在 v5 中，这些选项默认值为 false。在 v6 中，它们默认启用。这不会影响账单。

若要保留 v5 的行为，请仅显式禁用在 v5 中未启用的选项。如果某个选项在 v5 中已设为 true，则保持不变：

DD_RUM.init({
  trackUserInteractions: false, // only if not already true in v5
  trackResources: false, // only if not already true in v5
  trackLongTasks: false, // only if not already true in v5
})

3b. traceContextInjection 的默认值为 "sampled"

在 v5 中，所有请求都会注入跟踪上下文。在 v6 中，仅对已采样的跟踪注入。如果你的 traceSampleRate 为 100%（默认值），则不会产生影响。

若要保留 v5 的行为：

DD_RUM.init({
  traceContextInjection: 'all',
})

3c. tracecontext 传播器会添加 tracestate 标头

现在，tracecontext 传播器会额外发送一个 tracestate 标头。你的服务器必须接受此标头。将其添加到现有的 Access-Control-Allow-Headers 中，不要替换整个列表：

# Add tracestate alongside your existing headers
Access-Control-Allow-Headers: <existing-headers>, traceparent, tracestate

3d. site 参数采用强类型

site 选项使用更严格的 TypeScript 类型。如果传入非标准值，会出现类型错误。对于非标准的接入 URL，请改用 proxy。

搜索：grep -rn 'trackUserInteractions\|trackResources\|trackLongTasks\|traceContextInjection\|tracestate\|allowedTracingUrls\|propagatorTypes' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

还要搜索所有 RUM 初始化调用，找出省略这些选项且依赖 v5 中 false 默认值的项目：grep -rn 'DD_RUM\.init\|datadogRum\.init' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"。对于每个初始化调用，检查是否显式设置了 trackUserInteractions、trackResources 和 trackLongTasks；如果省略，这些选项在 v6 中的默认值现在为 true。

步骤 4：处理 Session Replay 延迟加载

现在，Session Replay 使用动态导入进行延迟加载。该模块只会在抽样用于回放的会话中加载，从而减小其他会话的捆绑包体积。

npm 设置

确保你的打包工具支持动态导入（代码拆分）。大多数现代打包工具都支持：

• Webpack：代码拆分文档
• Esbuild：拆分选项
• Rollup：代码拆分文档
• Parcel：代码拆分文档

CDN 设置

无需更改代码。录制时，SDK 会动态加载额外的代码块（例如 datadogRecorder-<hash>-datadog-rum.js）。如有需要，请更新 CSP script-src 规则以允许加载该代码块。

步骤 5：检查行为变更（无需修改代码，但可能需要留意）

变更	影响	必要时采取的操作
不再支持 IE11	SDK 使用 ES2018 目标构建。已移除 Polyfill。	如果需要支持 IE11，请继续使用 v5。
Long Animation Frames 取代 Long Tasks	在受支持的浏览器中，采集的是 Long Animation Frames，而非 Long Tasks。事件类型仍为 long_task。	如果你会检查 long task 事件详情，请进行确认。
Session cookie 过期时间延长至 1 年	支持匿名用户追踪。	设置 trackAnonymousUser: false 以选择退出。
RegExp 和 Event 对象经过清理	这些对象不再按原样序列化为上下文/属性。	如果之前传入的是 RegExp 或 Event 对象，请改用字符串表示形式。
不再采集 Webpack ChunkLoadError	减少 SDK 代码块加载失败产生的噪声。	无需操作。

步骤 6：更新基础设施

• 浏览器支持：以 ES2018 为基准。不再支持 IE11。
• CORS：如果使用 tracecontext 传播器，请在现有的 Access-Control-Allow-Headers 中添加 tracestate（不要替换整个列表）：Access-Control-Allow-Headers: <existing-headers>, traceparent, tracestate
• CSP：在 script-src 规则中允许动态加载的 Session Replay 分块（例如，datadogRecorder-*-datadog-rum.js）。
• 打包器配置：确保打包器支持动态导入，以便延迟加载 Session Replay。

常见错误

错误	问题	修复
出于防御目的禁用 trackUserInteractions、trackResources、trackLongTasks	禁用了项目所需的功能——这些功能现在默认值为 true，通常这正是期望的行为	仅在项目明确不需要这些功能时才将其设为 false；否则保持未设置，以采用新的默认值
Access-Control-Allow-Headers 中缺少 tracestate	tracecontext 传播器现在会发送 tracestate 标头——跨源请求会被 CORS 阻止	在服务器的 Access-Control-Allow-Headers 中，将 tracestate 与 traceparent 一起添加
未为延迟加载的 Session Replay 分块更新 CSP script-src	在受 CSP 限制的页面上，录制会静默失败——动态分块被阻止	在 script-src 中允许 datadogRecorder-*-datadog-rum.js

验证清单

升级后，请确认：

• SDK 加载时没有控制台错误
• 不再引用已移除的选项（useCrossSiteSessionCookie、sendLogsAfterSessionExpiration）
• Session Replay 录制正常工作（如果使用）
• 分布式追踪正常工作（没有由 tracestate 标头导致的 CORS 错误）
• 包体积已减小（已移除 IE11 polyfill）
• 仍会收集长任务（在受支持的浏览器中，现在以 Long Animation Frames 的形式收集）
• site 参数类型没有 TypeScript 错误