从 1.18 及更早版本升级

如果项目当前使用 1.18.x 或更早版本，升级到 1.19.0 及后续版本时，都需要检查本页列出的行为变化。1.19 不删除 1.x 已公开的初始化 API，但会把默认集成、事件字段和 tracing 行为对齐 Sentry JavaScript SDK。大多数只调用 Sentry.init({ dsn, release }) 的项目无需修改业务代码；依赖旧的集成装配方式、追踪头默认值或事件字段查询时，需要按本页调整。

升级前必须检查

显式配置追踪目标

tracePropagationTargets 默认为空时，1.19 不再向任意业务请求注入 sentry-trace、baggage 或 traceparent。需要串联后端链路的项目必须只加入自己控制的 API：

Sentry.init({
  dsn: 'YOUR_DSN',
  tracesSampleRate: 0.2,
  tracePropagationTargets: [
    'https://api.example.com',
    /^https:\/\/gateway\.example\.com\//,
  ],
});

这项默认值变化会让未配置白名单的分布式链路停止串联，但不会影响业务请求本身，也不会关闭错误上报或网络面包屑。

更新 integration 配置语义

integrations 数组现在追加到默认集合，并由同名用户实例覆盖默认实例；函数形式接收默认集合并返回最终集合。过去依赖 integrations: [...] 隐式关闭默认集成的项目，应显式配置：

Sentry.init({
  dsn: 'YOUR_DSN',
  defaultIntegrations: false,
  integrations: [Sentry.Integrations.globalHandlersIntegration()],
});

每次 init() 都应创建新的有状态 integration 实例。不要跨多次初始化复用 Sentry.defaultIntegrations 或缓存后的 Sentry.getDefaultIntegrations() 结果：

// 推荐：省略 defaultIntegrations，SDK 会在每次 init 时创建新实例
Sentry.init({
  dsn: 'YOUR_DSN',
});

Sentry.defaultIntegrations 仅为 1.x 源码兼容保留，已弃用。旧的 new Sentry.Integrations.Dedupe({ fuzzyMatch: true }) 仍可使用；新代码应使用 Sentry.Integrations.dedupeIntegration()。

更新 Sentry 查询和告警字段

1.19 对齐以下字段语义：

顶层 event.platform 固定为 javascript；微信、支付宝、字节跳动、百度、QQ、钉钉、快手等真实宿主位于 contexts.miniapp.platform。
contexts.app.app_version 表示小程序自身版本，app_identifier 表示 AppID。
宿主客户端和基础库版本位于 contexts.miniapp.host_version 与 contexts.miniapp.host_sdk_version。
event.sdk.packages 使用规范包名 npm:sentry-miniapp。

如果面板、Discover 查询或告警规则仍筛选旧的顶层平台或 app 版本含义，请在升级前迁移。

性能与错误数据变化

1.19.0 最初只在已有活跃 transaction 时创建 http.client 请求子 span，以避免为每个孤立请求创建根 transaction；后续补丁在保留子 span 行为的同时，将无父请求改为独立 segment span。这样小游戏长时间没有页面 transaction 时也不会丢失请求追踪，同时仍不会制造根 transaction。
Performance API 条目会转换为 Unix epoch 时间，并丢弃明显过旧、未来或异常的宿主时间值。
定时器和 requestAnimationFrame 回调中的异常捕获后仍会重新抛出，因此 mechanism 记为 handled: false。升级后 crash-free 指标或相关告警可能出现一次符合真实语义的变化。
异常构建、LinkedErrors、Dedupe、RewriteFrames 与反馈事件使用 @sentry/core 官方实现；少量 Issue 可能因更规范的堆栈或异常链重新分组。

从 1.18 及更早版本升级 ​

升级前必须检查 ​

显式配置追踪目标 ​

更新 integration 配置语义 ​

更新 Sentry 查询和告警字段 ​

性能与错误数据变化 ​

推荐验证 ​