必须在manifest.json中声明background.service_worker并设type为module，vscode断点需打在事件监听器内，chrome须以--remote-debugging-port启动，再通过chrome://extensions点击“service worker”唤醒并attach调试。
后台脚本无法断点？先确认 manifest.json 的 type 配置
Chrome 插件的后台脚本（background script）在 Manifest V3 中必须声明为 service_worker 类型，否则 VSCode 无法附加调试器。Manifest V2 的 background.scripts 或 background.page 已被弃用，强行使用会导致 DevTools 不显示 background 页面，debugger 语句也无效。
检查你的 manifest.json 是否包含：
{
"manifest_version": 3,
"background": {
"service_worker": "background.js",
"type": "module" // 可选，但若用 import/export 必须加
}
}
-
service_worker字段值必须是相对路径，且文件需真实存在；VSCode 调试器只识别 SW 入口，不支持background.html - 若 background.js 是 ES 模块（含
import），务必加"type": "module"，否则 Chrome 加载失败，VSCode 连接时会报Failed to load resource - 不要在
background下同时写scripts和service_worker，V3 会忽略前者
launch.json 怎么配？关键字段不能漏
VSCode 的 .vscode/launch.json 必须启用 chrome 调试类型，并指定 url 为 chrome-extension:// 协议地址 —— 这是唯一能触发后台脚本加载并允许断点的方式。
示例配置（替换 YOUR_EXTENSION_ID 为实际 ID）：
{
"version": "0.2.0",
"configurations": [
{
"type": "chrome",
"request": "attach",
"name": "Attach to Background",
"port": 9222,
"webRoot": "${workspaceFolder}",
"url": "chrome-extension://YOUR_EXTENSION_ID/background.js",
"sourceMapPathOverrides": {
"webpack:///./src/*": "${webRoot}/src/*"
}
}
]
}
-
port必须与 Chrome 启动时的远程调试端口一致（启动命令加--remote-debugging-port=9222） -
url中的 extension ID 不能手敲：打开chrome://extensions→ 开启「开发者模式」→ 找到你的插件 → 点击「详情」→ 复制 ID（一串小写字母和数字） -
sourceMapPathOverrides仅当使用构建工具（如 webpack、vite）时需要；纯 JS 文件可省略 - 别用
launch请求类型：后台脚本没有 HTML 容器，launch会尝试打开新窗口，失败且无法 attach
Chrome 启动命令必须带 --remote-debugging-port
VSCode 调试器通过 CDP（Chrome DevTools Protocol）连接 Chrome 实例，没开调试端口就等于没开门。直接双击启动的 Chrome 默认关闭该端口，必须从终端显式启动。
macOS/Linux 示例：
open -n -a "Google Chrome" --args --remote-debugging-port=9222 --load-extension=./dist
Windows 示例（PowerShell）：
Start-Process "chrome.exe" -ArgumentList "--remote-debugging-port=9222","--load-extension=C:\path\to\dist"
-
--load-extension参数值必须是扩展根目录（含manifest.json），不是打包后的 ZIP - 如果已有一个 Chrome 实例在运行，新实例会拒绝启动调试端口 —— 关掉所有 Chrome 进程再试
- Windows 上若提示找不到
chrome.exe，请用完整路径，例如"C:\Program Files\Google\Chrome\Application\chrome.exe" - 别用
--disable-web-security或其他无关参数干扰调试链路
断点不命中？检查脚本加载时机和 DevTools 标签
后台脚本在 service worker 生命周期中是懒加载的：只有事件（如 chrome.runtime.onInstalled）触发时才执行。单纯启动 Chrome 并不意味着 background.js 已运行，VSCode 断点自然不会生效。
- 首次加载插件后，手动刷新一次
chrome://extensions页面，或触发一个事件（比如点击插件图标、发一条chrome.runtime.sendMessage）来激活 service worker - 在 Chrome DevTools 中，切换到
Application → Service Workers标签，确认你的 worker 显示为「Running」状态；若为「Waiting」或「Redundant」，说明未激活 - VSCode 断点只对已加载并执行过的代码有效 —— 在
background.js顶部加console.log('loaded')，看是否输出，判断脚本是否真正跑起来了 - 如果用了
chrome.runtime.onMessage等异步监听，断点要打在回调函数内，而非顶层代码
最常被忽略的是：你以为插件已加载，其实只是被 Chrome 缓存了旧版本。每次改完 manifest.json 或 background.js 后，务必在 chrome://extensions 点「重新加载」，而不是仅刷新页面。
