workbox-google-analytics实现离线Analytics时SW报sync错误

云上老周

2026-10-24

报错排查与解决方案

报错本质

从调用栈可直接定位，错误发生在Workbox BackgroundSync模块的Queue._addSyncListener方法中：代码执行sync in self.registration检测时，self.registration为undefined，触发类型错误。

对应问题与解决方式

Workbox版本兼容bug
workbox-background-sync v6.0.0~v6.1.2区间存在已知问题：Queue初始化时的sync接口检测为异步逻辑，若此时Service Worker的registration对象尚未完成赋值，就会抛出该错误。因后续registration会自动补全，离线GA的队列存储、网络恢复后自动同步的功能不受影响。
解决方式：将所有Workbox相关依赖升级至v6.1.3及以上稳定版，或降级至v5.x版本，重新打包Service Worker代码即可消除报错。
代码执行时机错误
若googleAnalytics.initialize()的调用早于Service Worker activate生命周期触发，此时self.registration尚未完成初始化，也会触发该问题。
排查方式：在googleAnalytics.initialize()调用前添加console.log(self.registration)，若输出为undefined即可确认。解决方式是将初始化逻辑移入self.addEventListener('activate', () => { ... })回调中执行。
打包配置异常
若使用Rollup、Webpack等工具打包Service Worker，需确认配置未重写self/globalThis全局对象，避免registration对象被打包上下文遮蔽。
临时屏蔽报错方案
若暂不方便调整Workbox版本或执行时机，可在Service Worker全局作用域添加未捕获Promise错误监听，仅过滤该特定报错，不影响其他错误的捕获：
```
self.addEventListener('unhandledrejection', (event) => {
  if (event.reason.message.includes("Cannot use 'in' operator to search for 'sync' in undefined")) {
    event.preventDefault();
  }
});
```
该方式仅屏蔽控制台报错，不影响现有功能运行。