<p>断点停在 dist/index.js 错误行号是因 source map 映射链断裂：VSCode 依据 .map 文件中 sources 路径（如 webpack:///./src/index.ts）拼接 webRoot，若 webRoot 错位（如应为 ${workspaceFolder}/dist 却设为 ${workspaceFolder}），则路径拼接失败；sourceMapPathOverrides 需严格匹配 .map 中 sources 字段，如 "webpack:///./src/": "${webRoot}/src/"；outFiles 必须准确指向 JS 文件（含 ** 通配子目录），否则不加载 source map；唯一生效证据是调试控制台输出 "Loaded source map from:"。</p>
断点打在 src/index.ts 却停在 dist/index.js 的错误行号，说明 source map 映射链断裂了——不是 VSCode 读错了，是它从 .map 文件里拿到的源码路径（比如 webpack:///./src/index.ts）根本拼不出你本地磁盘上的真实路径。
为什么 webRoot 错一位，整个调试就失效
webRoot 是 VSCode 解析 sourceMapPathOverrides 的基底路径，不参与匹配，但所有右侧路径都以它为起点拼接。如果实际构建产物服务根目录是 ${workspaceFolder}/dist，而 webRoot 还设成 ${workspaceFolder}，那即使映射规则写对了，最终拼出的路径也会是 /Users/me/project/webpack:///src/index.ts 这种非法路径。
- React/Vue 项目常用
"webRoot": "${workspaceFolder}"，前提是开发服务器以项目根为服务路径（如 CRA 的public/和build/平级） - Vite +
base: "/admin/"或 Webpackoutput.path = path.resolve(__dirname, "out")时，webRoot必须设为"${workspaceFolder}/out" - 用
vite preview时默认不提供 .map 文件服务，需改用vite dev或配反向代理
sourceMapPathOverrides 必须按 .map 文件里的 sources 字段精确写
sourceMapPathOverrides 不是自动补全，是你手动写的键值对。VSCode 不会猜测、分析或学习路径，只做字符串替换。先打开 Chrome DevTools → Sources → 展开 webpack:// → 右键任意源文件 → “Reveal in sidebar”，复制完整路径（如 webpack:///./src/App.tsx），再粘贴进左侧作为 key。
- 常见写法：
"webpack:///./src/*": "${webRoot}/src/*"（注意./和斜杠方向） - 多包 monorepo 中，若路径是
webpack:///packages/core/src/index.ts，就不能用./src/*，得写"webpack:///packages/core/src/*": "${webRoot}/packages/core/src/*" - 避免泛化：
"webpack:///*": "${webRoot}/*"容易把node_modules里的路径也映射错
outFiles 路径不对，VSCode 根本不会加载任何 source map
outFiles 是调试器扫描 JS 文件的唯一入口，不是“建议路径”。它告诉 VSCode：“去这些 JS 文件里找 //# sourceMappingURL= 注释，并加载旁边的 .map”。写错一个字符，整个映射就中断。
- 必须是数组：
"outFiles": ["${workspaceFolder}/dist/**/*.js"]，不能漏掉**（否则子目录如dist/router/index.js被忽略） - 若构建输出到
lib/或build/，outFiles必须同步改，不能沿用dist/ - 多格式输出（如 Vite 的
dist/es/和dist/lib/）要全部列出来：["${workspaceFolder}/dist/es/**/*.js", "${workspaceFolder}/dist/lib/**/*.js"]
调试控制台里没看到 Loaded source map from: 就不算成功
断点变实心红圈不等于 source map 生效。真正证据只有一条：打开「调试控制台」（Debug Console），搜索 Loaded source map from:。出现这条日志，才说明 VSCode 成功读取并解析了 .map 文件。
- 如果只看到
Could not load source map或 404，优先检查outFiles是否扫到了 JS、.map 文件是否真实存在且可读 - 如果日志里有路径但断点仍偏移，大概率是构建时用了
inlineSourceMap: true或devtool: "cheap-module-source-map"，丢失列信息 - Node.js 调试时，若用
ts-node，别配outFiles，改用runtimeArgs: ["-r", "ts-node/register"]并关掉sourceMaps
