sourceFileMap 是 VS Code launch.json 中用于源码路径映射的配置项，解决 GDB 因本地与编译路径不一致导致断点不命中问题；需按 readelf 输出的 DWARF 路径精确配置前缀替换。
sourceFileMap 是什么，为什么必须配
sourceFileMap 是 VS Code 的 launch.json 中用于源码路径映射的关键配置项。它不解决“连不上”问题，只解决“断点不命中”——哪怕 gdbserver 正常运行、target remote 成功连接，只要本地路径和目标机上源码路径对不上，GDB 就找不到对应行号，断点永远是空心的。
根本原因是：GDB 从可执行文件的调试信息（DWARF）里读到的是编译时的绝对路径（比如 /home/build/project/src/main.cpp），而你本地打开的文件路径可能是 /Users/me/project/src/main.cpp。这两者不一致，GDB 就无法把断点位置关联到你正在编辑的文件上。
-
"sourceFileMap": { "/home/build/project/": "${workspaceFolder}/" }—— 把编译路径前缀替换成你当前工作区路径 - 必须是**完整路径前缀匹配**，不是模糊替换；少一个
/或多一个空格都会失败 - 大小写敏感（尤其在 Linux 目标机 + macOS/Windows 主机混合环境下）
- 如果编译时用了相对路径或
-fdebug-prefix-map，也要按实际生成的 DWARF 路径来反推映射关系
怎么查出编译时的真实路径
别猜，直接从可执行文件里看。在本地机器上运行：
readelf -wi ./your_program | grep "DW_AT_comp_dir\|DW_AT_name" | head -20
重点关注 DW_AT_comp_dir（编译工作目录）和紧随其后的 DW_AT_name（源文件名），拼起来就是 GDB 期望看到的完整路径。例如输出里有：
DW_AT_comp_dir: /home/build/project</code> <pre class="brush:php;toolbar:false;">DW_AT_name: src/main.cpp
那真实路径就是 /home/build/project/src/main.cpp，<code>sourceFileMap 就得写成：
"sourceFileMap": { "/home/build/project/": "${workspaceFolder}/" }
- 如果用 CMake 编译，检查是否加了
-fdebug-prefix-map=/build=/src这类参数，那就要按重映射后的路径来找 - 交叉编译环境下，路径往往来自构建机（如 Docker 容器或 CI 服务器），不是你的开发机，所以不能假设和本地路径一致
- CLion 和 VS Code 都依赖这个映射，但 CLion 有时会尝试自动推导，VS Code 完全靠手动填，错一点就白忙
常见映射错误现象和修复
断点灰色、hover 显示 “No symbol information for this location”、“Breakpoint ignored” 等提示，基本都指向 sourceFileMap 配置失效。
-
现象：断点设在
main.cpp第 10 行，但程序运行后不停 → 检查sourceFileMap是否覆盖了该文件的完整路径前缀，而不是只映射到src/ -
现象：部分文件能断，部分不能 → 编译时用了多个源码根目录（比如 submodule 或 out-of-tree build），需要多个映射条目，例如：
"sourceFileMap": { "/home/build/core/": "${workspaceFolder}/core/", "/home/build/ext/libfoo/": "${workspaceFolder}/third_party/libfoo/" } -
现象：改了
sourceFileMap还没用 → 重启 VS Code 调试会话（仅 reload window 不够），因为映射在 session 初始化时加载 - 现象：路径含中文或空格 → 确保两边路径都用双引号包裹，且 VS Code 版本 ≥1.80（旧版对非 ASCII 路径支持不稳定）
vscode launch.json 里 sourceFileMap 的写法细节
它不是正则，也不是 glob，是纯字符串前缀替换。所以写法非常机械，但容错率极低。
- 左边必须以
/开头，且结尾带/（否则可能误替换子目录，如/src会把/src_ext也替掉） - 右边推荐用
${workspaceFolder}/，不要写死绝对路径，否则换机器就崩 - 不支持环境变量展开（
${env:HOME}在这里无效） - 如果项目用 Bazel/Cargo 等工具，调试信息里的路径可能带
bazel-out/或target/debug/deps/，要照着readelf输出来配，不能凭经验猜
最麻烦的点在于：它只在你第一次 hit 断点时默默生效或失败，没有日志、不报错、也不提示哪里不对——你得靠 readelf 和反复试出来。路径映射这事，看起来只是配两行 JSON，实际是远程调试里最耗时间的隐形瓶颈。
