sourcemappathoverrides是手动编写的键值对映射表，非自动补全；需根据chrome devtools中sources面板显示的实际sourcemap路径（如webpack:///./src/app.tsx）与本地磁盘路径（如${webroot}/src/app.tsx）精准配置，webroot设错将导致整个映射失效。
sourceMapPathOverrides 不是自动补全，而是手动映射规则
VSCode 调试器本身不会“动态补全”路径，sourceMapPathOverrides 是你写死的键值对映射表，它不分析文件结构、不猜测路径、也不学习历史行为。所谓“动态”，只是指你在不同项目中需根据构建产物里 sources 字段的实际内容，手工调整右侧本地路径——比如从 "webpack:///src/*" 改成 "webpack:///app/*"，本质是人驱动的适配。
常见错误现象：
- 断点显示为空心红点，Sources 面板里看不到
src/目录树 - Chrome DevTools 的
Sources → webpack://下路径是webpack:///./packages/core/src/index.ts，但你的文件实际在${workspaceFolder}/packages/core/src/ - 配置了
"webpack:///src/*": "${webRoot}/src/*"却仍找不到文件——因为 sourcemap 里压根没出现/src/，而是/packages/core/src/
实操建议：
- 先打开 Chrome DevTools → Sources → 展开
webpack://，右键任意源文件 → “Reveal in sidebar”，看完整路径字符串（复制出来） - 把该路径粘贴进
sourceMapPathOverrides左侧，用*替换变动部分；右侧用${workspaceFolder}或${webRoot}拼出真实磁盘路径 - 避免过度泛化，例如
"webpack:///*": "${webRoot}/*"在多包 monorepo 中容易误映射 node_modules 内部路径
为什么 webRoot 错一位，整个 sourceMapPathOverrides 就失效
webRoot 是 VSCode 解析 sourceMapPathOverrides 的锚点。它不参与匹配，但所有右侧路径拼接都以它为基底。如果 webRoot 指向 ${workspaceFolder}，而实际 HTML 入口和构建产物在 dist/ 子目录下，那即使 sourceMapPathOverrides 写对了，拼出来的路径也会是 /Users/me/project/webpack:///src/App.ts 这种非法路径。
使用场景：
- CRA 项目：通常
webRoot设为${workspaceFolder}，因为public/index.html和编译后build/是平级 - Vite +
base: "/admin/"：若index.html部署在子路径，webRoot仍应指向项目根，但sourceMapPathOverrides右侧需补全dist/目录 - Webpack output.path =
path.resolve(__dirname, "out")：则webRoot应设为${workspaceFolder}/out，否则右侧路径永远找不到文件
性能影响：无直接性能损耗，但 webRoot 错误会导致 VSCode 每次断点命中都做一次无效的文件系统查找，拖慢调试响应。
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
outFiles 和 sourceMapPathOverrides 的协作边界在哪
outFiles 告诉 VSCode：“这些 JS 文件是编译产物，请去它们的 .map 里找源码”；sourceMapPathOverrides 则负责把 .map 里写的虚拟路径（如 webpack:///src/App.ts）翻译成真实路径（如 /Users/me/project/src/App.ts）。两者缺一不可，且顺序固定：先靠 outFiles 定位到正确的 .map，再靠 sourceMapPathOverrides 解析其中的 sources。
容易踩的坑：
-
outFiles写成["${workspaceFolder}/src/**/*.ts"]—— 这是源码路径，不是编译后 JS 路径，VSCode 根本不会加载任何 sourcemap - 多输出目录（如
dist/es/和dist/cjs/）只写了其中一个，导致部分模块断点失效 - Vite 用户在
build.sourcemap: true开启后，outFiles指向dist/*.js，但 Vite 默认生成的是dist/assets/index.xxxx.js，路径不匹配
参数差异：
- Webpack：常用
outFiles: ["${workspaceFolder}/dist/**/*.js"] - Vite：推荐
outFiles: ["${workspaceFolder}/dist/**/*.{js,jsx,ts,tsx}"]，并确认build.rollupOptions.output.entryFileNames未改写默认结构 - TS + tsc：若不用构建工具，
outFiles应与tsconfig.json中outDir一致
Vue / React / Svelte 框架特有的路径偏移陷阱
框架编译器会重写 AST 并注入运行时代码，导致 sourcemap 的 sources 字段出现非直觉路径。例如 Vue 的 <script setup></script> 编译后路径可能是 webpack:///src/components/Hello.vue?vue&type=script&setup=true&lang=ts，React 的 JSX 会被转成 React.createElement 调用，Svelte 的 $: 响应式声明会生成闭包函数——这些都会让原始行号和变量名映射失真。
实操建议：
- Vue 3：
sourceMapPathOverrides加一条"webpack:///?*": "${webRoot}/*"，用于匹配带查询参数的虚拟路径 - React（CRA）：
outFiles必须包含build/static/js/*.js，且sourceMapPathOverrides中"webpack:///src/*"对应的是 CRA 的src/目录，不是你自定义的别名路径 - SvelteKit：若用
adapter-static，webRoot应设为${workspaceFolder}/.svelte-kit/output/client，而非项目根目录 - 所有框架：禁用
skipFiles中的"**/node_modules/**"后，首次调试可能卡顿——这是 VSCode 正在解析第三方库 sourcemap，属正常现象
最易被忽略的一点：框架的 dev server（如 vite dev、webpack serve）可能把 sourcemap 写入内存文件系统（webpack://），而非磁盘；此时 sourceMapPathOverrides 的右侧必须用 ${webRoot}，不能硬写绝对路径——否则映射成功但文件读取失败。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
