断点灰色（unbound breakpoint）主因是vscode无法映射源码与运行代码：chrome未启用--remote-debugging-port、launch.json配置不匹配、source map路径或生成失效——三者缺一不可。
能调试，但必须满足三个硬性条件：Chrome 启动时带 --remote-debugging-port 参数、launch.json 用 launch 或 attach 模式配对、源码路径与 source map 映射一致——缺一不可，否则断点一定灰。
为什么断点是灰色的（Unbound breakpoint）
这是最常卡住的地方，不是插件没装好，而是 VSCode 根本找不到你代码和浏览器里运行代码的对应关系。
-
webRoot路径错：比如 Vite 项目源码在src/，却设成"${workspaceFolder}"，VSCode 就无法把webpack:///src/App.tsx映射回本地文件 - Chrome 已有其他实例占了
9222端口：关掉所有 Chrome 窗口（包括后台进程），或改用9223并同步更新port和runtimeArgs - 没开 source map：Vite 用户检查
vite.config.ts中build.sourcemap是否为true；Webpack 用户确认devtool: 'source-map'；浏览器 Sources 面板里看不到.ts或.jsx文件，说明 source map 没生效 - 断点打在动态插入的脚本上：比如用
eval()或模板字符串拼的<script></script>，这类代码不会被 sourcemap 覆盖，断点必然无效
launch.json 必须配对的三项关键字段
复制网上的配置大概率失效，因为 url、webRoot、type 必须和你的实际运行方式严格一致。
-
url必须是完整可访问地址：写"http://localhost:5173/"，不能写"localhost:5173"或漏掉末尾斜杠；file://协议极难配通，不建议用 -
webRoot必须指向源码根目录：Vite 默认是"${workspaceFolder}/src"，Create React App 是"${workspaceFolder}/src"，纯 HTML 项目可能是"${workspaceFolder}" -
type推荐用"pwa-chrome"：旧的"chrome"类型在 VSCode 1.8x+ 后已逐步弃用，pwa-chrome支持 ES modules 和现代调试功能
一个最小可用配置示例：
{
"version": "0.2.0",
"configurations": [
{
"type": "pwa-chrome",
"request": "launch",
"name": "Launch localhost",
"url": "http://localhost:5173/",
"webRoot": "${workspaceFolder}/src",
"port": 9222,
"runtimeArgs": ["--remote-debugging-port=9222"]
}
]
}
用 attach 模式连已打开的 Chrome 页面
适合临时排查线上页面或不想让 VSCode 自己拉起新浏览器的场景，但限制更多，容易连不上。
- Chrome 必须提前从终端启动：
chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug（macOS/Linux）或 Windows 命令行执行，双击图标启动的 Chrome 不带调试端口 -
launch.json中request必须是"attach"，不能是"launch"；url字段留空，改用urlFilter更可靠，比如"*localhost:5173*" - VSCode 不会自动发现页面，它只查
http://localhost:9222/json返回的 tab 列表，所以urlFilter匹配不到就等于“没这个页面”
attach 配置片段：
{
"type": "pwa-chrome",
"request": "attach",
"name": "Attach to Chrome",
"port": 9222,
"urlFilter": "*localhost:5173*",
"webRoot": "${workspaceFolder}/src"
}
Chrome 启动参数和端口冲突是最隐蔽的失败点
很多人反复重装插件、重写配置，最后发现只是 Chrome 进程没关干净，或者防火墙/杀毒软件拦截了 9222 端口通信。
- macOS 上 Spotlight 启动的 Chrome 忽略命令行参数，必须终端执行；Windows 双击图标也一样，得用快捷方式或批处理调用
- 用
lsof -i :9222（macOS/Linux）或netstat -ano | findstr :9222（Windows）确认端口是否真被占用 -
--user-data-dir参数不是可选的：不加会导致 Chrome 报错或调试器连接不稳定，尤其 macOS 上常见 - VSCode 状态栏右下角出现 Chrome 图标且显示
DEBUGGING，才代表连接真正建立成功；光看到浏览器弹出来不代表调试就绪
