<p>VSCode调试Chrome插件background脚本需理解Manifest V3的Service Worker机制：必须正确声明service_worker路径、启用type: "module"，所有chrome.* API调用须在事件监听器内，调试前需手动重载扩展并打开"inspect views"唤醒SW。</p>
VSCode 里写 Chrome 插件的 background 脚本，缺的不是代码能力，而是对 Manifest V3 后台机制的理解——chrome.* API 不是“自动可用”的，它只在 Service Worker 上下文中、且被正确唤醒后才生效。直接写 chrome.runtime.onInstalled 却断点不触发？大概率是没唤醒 SW，或 manifest.json 声明错了。
manifest.json 的 background 字段必须严格按 V3 写法
Manifest V2 的 background.page 或 scripts 数组已彻底废弃，V3 只认 service_worker 字段。常见错误包括：
-
"background": {"scripts": ["background.js"]}—— 这会静默失败，Chrome 根本不加载脚本 -
"service_worker": "./background.js"—— 路径带./前缀，Chrome 不识别，必须写成"background.js"（相对manifest.json所在目录） - 漏掉
"type": "module"导致import报错（虽非强制，但现代写法基本都要加）
正确示例：
{
"background": {
"service_worker": "background.js",
"type": "module"
}
}chrome.* API 在顶层作用域不可用
Service Worker 是事件驱动的，不是常驻进程。你在 background.js 文件最外层写的 console.log(chrome.runtime) 或 debugger 永远不会执行——SW 根本没启动。
- 所有
chrome.*调用必须包裹在事件监听器内，例如chrome.runtime.onInstalled、chrome.runtime.onMessage、chrome.alarms.onAlarm - 调试时断点只能打在这些回调函数内部，比如
chrome.runtime.onInstalled.addListener(() => { debugger; }) - 不要依赖“刷新页面”来重载 background 脚本；改完代码后需手动点击 chrome://extensions → “重新加载”，再触发对应事件
VSCode 断点不命中？先确认 Chrome 是否以调试模式启动
VSCode 的 attach 模式依赖 Chrome 的远程调试协议，没开端口就等于没通电。
- 必须关闭所有 Chrome 进程（Windows：任务管理器杀光 chrome.exe；macOS/Linux：
pkill -f "chrome.*9222"） - 命令行启动 Chrome：
chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug（--user-data-dir是必须项，否则端口可能被占用） -
launch.json中port必须和启动参数一致；urlFilter必须写死为"chrome-extension://*/_generated_background_page.html"，不能替换成你的扩展 ID 或本地路径 - 断点前务必先打开
chrome://extensions，点击你扩展的 “inspect views: service worker” —— 这一步才是真正唤醒 SW 并建立 DevTools 连接
chrome.runtime API 报 undefined？检查运行时上下文
chrome.runtime 在 background script 中可用，但在 content script 或 popup 页面中默认不可用（除非显式声明 "permissions": ["runtime"]）。但更隐蔽的问题是：
- 如果 background 脚本是通过
import引入其他模块，而该模块试图在顶层访问chrome.runtime，依然会报错 —— 因为 import 时机早于 SW 生命周期 - 某些 API（如
chrome.storage.local.get）在 SW 初始化完成前调用会静默失败，建议封装成 Promise 并 awaitchrome.runtime.onStartup后再执行关键逻辑 - V3 中
chrome.extension已完全移除，别再用它做消息传递或资源加载
真正容易被忽略的是：Service Worker 的生命周期极短，一次事件处理完就可能被终止。任何长期轮询、setInterval 或未 resolve 的 Promise 都会导致行为不可预测——这不是 VSCode 的问题，是 V3 的底层约束。
