断点变灰是因VSCode无法匹配源码与运行代码，核心在于source map路径错误；需确保生成source-map、正确配置outFiles和sourceMapPathOverrides，并验证.map文件真实存在。
断点变灰不是插件坏了，是 VSCode 找不到源码和运行代码之间的对应关系——核心就是 source map 路径没对上。
sourceMap 没生成或类型不兼容 VSCode
VSCode 的 JavaScript Debugger（pwa-chrome 或 pwa-node）只认物理存在的 .js.map 文件，或者从 1.70+ 开始能解析 inline-source-map。但以下几种 devtool 值会导致断点失效：
-
eval-source-map：map 塞在eval()字符串里，VSCode 无法提取 -
cheap-module-source-map：丢失列信息，JSX/TSX 行内表达式断点容易偏移 -
hidden-source-map：不写//# sourceMappingURL=注释，VSCode 和 Chrome 都找不到
必须改用：
-
source-map（推荐）：生成独立main.js.map，路径清晰，调试最稳 -
inline-source-map：map 内联在 JS 末尾 base64 编码，需 VSCode ≥1.70，某些代理环境可能截断注释
Vue CLI 项目要在 vue.config.js 的 configureWebpack.devtool 里显式设，chainWebpack 中调 devtool() 无效；Next.js 若覆盖了 webpack 配置，也得手动加。
launch.json 的 outFiles 和 sourceMapPathOverrides 配错
outFiles 是 VSCode 查找编译后 JS 的起点，填错就等于放弃解析。它必须精确匹配真实输出的 JS 文件路径：
- ✅ 正确：
"${workspaceFolder}/dist/**/*.js"（注意**/*.js） - ❌ 错误：
"./dist/**"（漏扩展名）、"../dist/**/*.js"（相对路径跨平台易错）、"${workspaceFolder}/src/**/*.js"（那是源码，不是产物）
sourceMapPathOverrides 用来把 sourcemap 里的虚拟路径（如 webpack:///./src/App.tsx）映射到你本地磁盘路径。常见错误：
- Chrome Sources 面板右键“Reveal in sidebar”，看前缀是
webpack:///./src/还是webpack:///src/，少一个/或.就匹配失败 -
webRoot必须是你开发服务器服务的根目录，比如index.html在dist/下、服务以dist/为 root，那webRoot就该是"${workspaceFolder}/dist"，不是"${workspaceFolder}" - monorepo 项目要额外加映射，例如
"webpack:///@mylib/*": "${webRoot}/packages/mylib/*"
TypeScript 项目三处 sourceMap 必须全开且路径一致
TypeScript 调试失败，往往卡在三个地方没对齐：
-
tsconfig.json中"sourceMap": true（必开），"inlineSourceMap": false（避免和devtool冲突），"outDir": "./dist"（明确输出位置） - 构建工具（Webpack/Vite）的
devtool设为source-map，且确保outDir和tsconfig.json一致 -
launch.json中"outFiles"必须指向同一outDir下的 JS 文件，比如"${workspaceFolder}/dist/**/*.js"
改完记得 Ctrl+S 保存所有配置文件，然后停止当前 dev server 和调试会话，重新 npm run dev（或等自动重编译完成），再点 ▶️ 启动调试——复用旧会话，加载的还是老符号。
断点灰但 Chrome 能跳源码？说明 VSCode 没拿到映射结果
这是典型“Chrome 解析出来了，VSCode 拼路径失败”。VSCode 不自己解析 .map，而是靠 Chrome DAP 协议传过来的原始路径（如 webpack:///src/App.tsx:12:5），再用 webRoot 和 sourceMapPathOverrides 去本地找文件。
- 先确认 Chrome DevTools 的 Sources 面板里，是否真能展开
webpack:///下的源码结构；不能，则是构建阶段就没生成 map - 能展开但 VSCode 断点灰，重点查
sourceMapPathOverrides的 key 是否和 Chrome 显示的前缀完全一致（包括斜杠数量、点号、大小写） - Vite 用户注意：
vite build默认不生成 .map，必须在vite.config.ts显式加build.sourcemap: true；vite preview默认不提供 .map 服务，建议改用vite dev调试
最常被忽略的是：改完配置后没验证 dist/*.js.map 文件是否真实生成、时间戳是否更新。别猜，直接 ls -l dist/*.map 看一眼。
