断点变灰但Chrome能跳源码，说明VSCode未正确关联Chrome解析出的原始路径，根源在于webRoot或sourceMapPathOverrides配置错误，导致本地文件路径匹配失败。
断点变灰但 Chrome DevTools 能跳源码，说明什么
说明 VSCode 没拿到映射信息，不是没生成 source map，而是调试器没把 Chrome 解析出的原始路径正确关联到你本地文件。VSCode 本身不解析 .map 文件，它靠 Chrome 的 DAP 协议把“我在 webpack:///src/App.tsx 第12行”这个位置传过来，再用 webRoot 和 sourceMapPathOverrides 去拼出真实路径。拼错，就找不到文件，断点变灰。
常见现象包括：Chrome Sources 面板里能看到 webpack:///src/ 结构，VSCode 里却打不上断点；悬停提示 “unbound breakpoint”；outFiles 路径没错，但断点仍无效。
-
webRoot必须匹配你服务的实际根目录——如果index.html在dist/下，且开发服务器以dist/为 web root，则webRoot应设为"${workspaceFolder}/dist"，不是"${workspaceFolder}" -
sourceMapPathOverrides中的 key（如"webpack:///./src/*"）必须和 .map 文件里sources字段完全一致，少一个/或*都会失败 - Vite 用户注意：
vite build默认不生成 .map，必须在vite.config.ts显式加build.sourcemap: true；而vite preview默认不提供 .map 文件服务，需配preview.host+ 反向代理或改用vite dev
Webpack 的 devtool 设置怎么选才不影响 VSCode 断点
devtool 决定是否产出可被 VSCode 加载的独立 .map 文件。很多项目用 'eval-source-map'，它把 map 嵌在 JS 末尾 base64 编码里，Chrome 能用，但 VSCode 的调试器无法提取——因为 outFiles 只认物理存在的 .js 和同目录下的 .js.map。
真正兼容 VSCode 调试的选项只有两类：
-
'source-map'：生成独立.js.map文件，路径正确、内容完整，VSCode 可靠加载 -
'inline-source-map'：map 以 base64 形式内联在 JS 末尾，VSCode 从 1.70+ 开始支持解析，但某些旧版插件或远程调试场景下仍不稳定 - 避免
'hidden-source-map'：它生成 .map 文件但不写//# sourceMappingURL=注释，VSCode 和 Chrome 都找不到 - 慎用
'cheap-module-source-map'：丢失列信息，断点可能偏移，尤其对 JSX/TSX 行内表达式不友好
outFiles 配置错在哪种情况最致命
outFiles 是 VSCode 查找 .map 的起点，填错等于直接放弃解析。它必须精确指向编译后的真实 JS 文件路径，而不是源码路径、也不是打包前的中间产物。
典型错误：
- 写成
["./dist/**/*.js"]：相对路径在多工作区或远程 SSH 场景下失效，必须用"${workspaceFolder}/dist/**/*.js" - 漏掉多出口目录：比如同时输出
dist/es/和dist/cjs/，只写["${workspaceFolder}/dist/es/**/*.js"]，CJS 版本的断点就永远无效 - 混用 glob 模式：写成
["${workspaceFolder}/dist/**"]不带/*.js，VSCode 会尝试加载.map对应的非 JS 文件，报错并跳过整个匹配 - TypeScript 项目里误写
outFiles指向.ts：它只接受 JS 文件路径，.ts文件会被忽略
多包 monorepo 项目如何让 source map 映射不漏文件
monorepo（如 pnpm workspace / turborepo）中，各包源码分散在 packages/foo/src、packages/bar/src 等路径，但默认的 sourceMapPathOverrides 往往只覆盖 src/，导致子包断点失效。
关键不是改 webRoot，而是扩展映射规则：
- 在
sourceMapPathOverrides中加一行："webpack:///../packages/*/src/*": "${workspaceFolder}/packages/*/src/*"，注意这里用../是因为 Webpack 默认把packages/foo/src解析为相对于 workspace 根的上层路径 - 若用 Turborepo，构建产物可能在
.turbo或各包dist/下，对应调整outFiles：["${workspaceFolder}/packages/**/dist/**/*.js"] - 配合
resolveSourceMapLocations排除干扰："resolveSourceMapLocations": ["${workspaceFolder}/packages/**/src/**", "!**/node_modules/**"]，防止 VSCode 错把依赖包的 .map 当成本地源码
最易被忽略的是：改完 launch.json 后，必须重启整个调试会话（不只是刷新页面），否则 VSCode 仍用旧缓存的路径映射关系。
