必须启用 Chrome 远程调试端口（如 --remote-debugging-port=9222）并配合 VSCode 的 attach 模式、正确 urlFilter 和 webRoot 配置，才能成功调试外部页面；否则会出现连接失败或断点不命中。
Chrome 必须启用远程调试端口
VSCode 调试外部 Chrome 页面的前提，不是“连上浏览器”，而是 Chrome 进程本身得暴露一个可被 VSCode（即 Debugger for Chrome / Edge 扩展）通信的调试接口。这个接口默认关闭，必须手动启动 Chrome 时带上 --remote-debugging-port=9222 参数。
常见错误现象：Unable to attach to browser、Connection refused、VSCode launch 配置里选不到目标页面——八成是 Chrome 根本没开这个端口。
- Windows/macOS/Linux 均需从命令行启动 Chrome（而非点击图标），例如：
chrome --remote-debugging-port=9222 --no-first-run --no-default-browser-check - 不能复用系统默认启动的 Chrome 实例；即使你之前用过该参数，关掉再点图标打开，端口就没了
- 端口号可换（如
9223），但 VSCode 的launch.json中port字段必须严格一致 - macOS 上若用 Spotlight 启动 Chrome，它会忽略命令行参数；必须终端执行或创建可执行脚本
VSCode 的 launch.json 需配置为 attach 模式
很多人卡在“找不到页面”或“断点灰了”，其实是误用了 launch 类型（它会自己拉起新 Chrome）。要附加到已打开的页面，必须用 attach 类型，并指定正确的 url 或 webRoot。
关键区别：launch 是“我来开浏览器”，attach 是“我去连你已开的浏览器”。VSCode 不会自动发现页面，它只查 http://localhost:9222/json 返回的 tab 列表，然后按 url 匹配。
-
type必须是chrome（或pwa-chrome，推荐后者，兼容性更好） -
request必须是attach -
port必须与 Chrome 启动时的--remote-debugging-port一致 -
url推荐留空，改用urlFilter（如*localhost:3000*）更可靠；否则必须完全匹配地址（含http://、端口、路径） -
webRoot必须指向你本地源码根目录（比如"${workspaceFolder}/src"），否则断点映射失败，点不生效
示例最小可用配置：
{
"type": "pwa-chrome",
"request": "attach",
"name": "Attach to Chrome",
"port": 9222,
"urlFilter": "*localhost:3000*",
"webRoot": "${workspaceFolder}/src"
}
断点不命中？大概率是 sourcemap 或路径映射问题
即使 Chrome 端口通了、VSCode 连上了、页面也列出来了，断点仍灰色或跳过，核心原因几乎全是调试器找不到源码位置——也就是 sourcemap 没生成，或生成了但 webRoot 和实际运行时 URL 路径对不上。
典型表现：Breakpoint ignored because generated code not found、断点打在 .ts 文件却停在 .js 上、F5 单步进不去函数内部。
- 确保构建工具（Vite/Webpack/ESBuild）开启了 sourcemap：Webpack 用
devtool: 'source-map'，Vite 默认开启但检查vite.config.ts中build.sourcemap是否为true - Chrome DevTools 里按
Cmd+P（macOS）或Ctrl+P（Win/Linux）搜你的 .ts 文件，如果搜不到，说明 sourcemap 没加载或路径错了 -
webRoot是本地路径，而 Chrome 加载的是http://localhost:3000/src/index.ts这类 URL；VSCode 用webRoot去“替换” URL 前缀，所以若实际 URL 是http://localhost:3000/app/src/，webRoot就得设为"${workspaceFolder}/app/src" - 避免使用相对路径别名（如
@/components），VSCode 调试器不解析这些，必须用真实文件路径
多个 Chrome 实例或用户配置干扰
Chrome 多用户、多 Profile、多实例并存时，--remote-debugging-port 只对当前启动的进程有效。如果你同时开着普通 Chrome 和调试版 Chrome，VSCode 可能连错进程，或者根本连不上——因为调试端口被另一个无头进程占了。
最容易被忽略的一点：Chrome 的用户数据目录（User Data Dir）和调试端口强绑定。不同用户目录 = 不同的 localhost:9222/json 接口。
- 启动调试版 Chrome 时，显式指定独立用户目录，避免和日常浏览器冲突：
chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug - 检查端口占用：
lsof -i :9222（macOS/Linux）或netstat -ano | findstr :9222（Windows），确认只有你要的那个 chrome.exe 在监听 - 关闭所有 Chrome 窗口后，任务管理器里仍可能残留 chrome.exe 进程，手动杀掉再重试
- Edge 浏览器同理，但调试类型应为
pwa-msedge，且端口不能和 Chrome 冲突
真正麻烦的从来不是“怎么连”，而是 Chrome 进程状态不可见、sourcemap 映射链断裂、以及 VSCode 对 URL 路径的静默替换逻辑——这些地方一错，断点就彻底失联。
