服务工作者调试

服务工作者看不见摸不着，调试入口和网页不太一样。但你只要记一个地方——chrome://extensions——几乎所有后台问题都能在这里定位。这一节手把手带你走一遍调试流程。

15-1 打开开发者模式

先在地址栏输入 chrome://extensions（Edge 同样支持）回车。页面右上角有一个”开发者模式”开关，把它打开。只有开了开发者模式，扩展卡片上才会显示加载、打包、以及服务工作者调试相关的入口。

打开后，你加载的每一个扩展都会显示一张卡片，里面有名称、ID、版本，以及一排按钮。我们要找的”服务工作者调试”就藏在这里。

15-2 打开服务工作者检查视图

在扩展卡片上，清单声明了 background.service_worker 的扩展，会显示一行”Service Worker”（或”检查视图：Service Worker”）的链接。点它，会弹出一个独立的 DevTools 窗口，这就是服务工作者的调试面板。

这个面板和网页的 DevTools 几乎一样：Console 看日志、Sources 看源码打断点、Network 看请求。你后台脚本里 console.log 的输出，就会实时出现在这里。

15-3 看懂 console 日志

后台调试最常用的是 Console 面板。在后台脚本里随手打日志，是排查”事件有没有触发""数据对不对”的最快手段。

chrome.runtime.onInstalled.addListener(() => {
  console.log('扩展已安装，开始初始化');
  chrome.storage.local.set({ init: true });
  console.log('初始化完成');
});

一个小细节：服务工作者每次被唤醒都会重新执行脚本。所以你会看到 console.log 在每次唤醒时重复打印——这是正常的，不是代码跑了两遍，而是”又醒一次”。

15-4 强制重新加载扩展

改了后台代码之后，必须让扩展重新加载，新代码才会生效。在扩展卡片上点”重新加载”（图标是个圆形箭头）即可。这一步等价于重新注册服务工作者，老脚本被丢弃、新脚本生效。

如果不重新加载，你改的 background.js 不会自动套用，调试时会非常困惑：“我明明改了，怎么还是老样子？“要注意，前台页面热刷新不等于后台刷新，后台一定要手动 reload。

15-5 常见报错一：Service worker registration failed

后台脚本写错、或清单指向的文件不存在，加载时就会看到这类错误：

Service worker registration failed. Status code: 15.

也可能是 Status code: 3（脚本拉取失败）。常见原因：

• manifest.json 里 background.service_worker 指向的文件名拼错、或文件根本没放进扩展目录。
• 后台脚本里有语法错误，浏览器解析失败无法注册。
• 用了 type: "module" 但 import 路径不对，模块加载不到。

排查顺序：先看 chrome://extensions 卡片上的”错误”按钮（红色字样），点开会列出具体错误；再对照文件名、路径、语法逐条核对。

15-6 常见报错二：监听函数报错

事件注册成功、但回调函数里出错，控制台会打印运行时异常：

Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')

这类错误往往是因为你调用的 API 对象不存在——例如拼写错、或忘了在清单里申请对应权限。一个典型例子是大小写写错：

// ❌ 拼写错误：oninstalled 不等于 onInstalled
chrome.runtime.oninstalled.addListener(() => { ... });

chrome.runtime.oninstalled 是 undefined，对它调 addListener 就直接崩。这种错很隐蔽，因为代码能注册成功（只是注册了个不存在的对象），只有运行时才暴露。遇到 Cannot read properties of undefined，先检查前面那个对象名有没有拼错。

15-7 用”错误”按钮快速定位

扩展卡片上还有一个”错误”按钮（有问题时显示为红色）。点开它能看到浏览器在加载/运行扩展时记录的所有错误信息，包括清单错误和后台脚本异常。调试时第一反应就应该是：先看这个按钮亮没亮，亮了点开看具体哪行错。

15-8 调试心法

最后给一套固定流程，遇到后台问题照着走：

1. 开 chrome://extensions 开发者模式。
2. 看卡片”错误”按钮是否变红，有就点开读原文。
3. 点”Service Worker”打开调试面板，在 Console 看日志。
4. 改完代码，点卡片”重新加载”让新后台生效。
5. 触发对应事件，确认日志和逻辑符合预期。

把这套流程刻进肌肉记忆，服务工作者对你来说就从”黑盒”变成了”透明盒”。

15-9 在 Sources 里打断点与看存储

除了看日志，调试面板里的 Sources 面板也很有用。它能看到后台脚本的真实源码，你可以在某一行点一下加断点，下次事件触发走到那行就会暂停，方便逐步看清变量值。注意服务工作者被停止后断点可能失效，调试前先触发一次把它唤醒，再下断点更稳。

想确认持久化数据有没有写对，不用自己写读取代码——在 chrome://extensions 卡片上点”查看视图”打开面板后，控制台里直接调：

// 在 Service Worker 控制台执行，查看当前存储内容
await chrome.storage.local.get(null);

这行会返回所有已存的 local 数据，立刻验证你的 set 是否真的生效。比起反复改代码打印，这种即时查询更快定位”是没存进去，还是没读出来”。