Source Map 是一种记录编译后代码与源代码位置映射关系的 JSON 文件，使 VS Code 能在原始源码（如 TypeScript）上设置断点并调试运行时的 JavaScript。调试时，VS Code 通过 launch.json 配置启动 Node.js 或浏览器环境，运行时加载 sourceMappingURL 指向的 map 文件，由底层引擎解析映射关系，将源码断点转换为生成代码中的实际断点位置。例如，在调试 TypeScript 时需在 tsconfig.json 中启用 "sourceMap": true，并在 launch.json 中指定 program 入口和 outFiles 生成路径，VS Code 即可自动关联 source map 并展示对应源码行。常见注意事项包括确保 map 文件正确生成、sourceMappingURL 存在、路径可匹配（可通过 sourceRoot 调整），以及生产环境避免泄露源码。浏览器调试机制类似，依赖相同原理实现源码级调试。
VS Code 调试 JavaScript 时，如果代码经过编译或打包（比如 TypeScript、Babel、Webpack 处理过），源文件和运行时的代码不一致，直接断点会失效。这时候就需要 Source Map 来建立映射关系，让 VS Code 能在原始源码上设置断点并单步调试。
Source Map 是什么？
Source Map 是一个 JSON 文件，记录了压缩/编译后的代码（生成代码）与原始源代码之间的位置对应关系。它告诉调试器：当前运行的某一行某一个字符，实际来自哪个源文件的哪一行哪一列。
例如，你写的是 TypeScript，被编译成 JavaScript，同时生成 .js.map 文件。浏览器或 Node.js 运行的是 JS，但调试器可以通过 map 文件“反查”到对应的 TS 代码行。
VS Code 如何利用 Source Map 调试？
VS Code 自身不执行代码，它通过调试适配器（如 Node.js 的 debugger 协议，或 Chrome DevTools Protocol）连接运行环境。调试过程中，Source Map 的解析由底层引擎（V8）和调试协议共同完成，VS Code 展示结果。
立即学习“Java免费学习笔记（深入）”；
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
- 启动调试时，VS Code 根据
launch.json配置启动 Node.js 或附加到浏览器 - 运行环境（如 Node.js）加载 JavaScript，并检查文件末尾是否有
//# sourceMappingURL=xxx.js.map - 如果有，运行环境读取 map 文件，建立生成代码 → 源代码的映射表
- 你在 VS Code 的原始文件（如 .ts）中设断点，编辑器将断点位置发送给调试器
- 调试器根据映射表，把源码断点转换成生成代码中的实际位置，在真实运行代码中设断点
- 当代码执行到该位置，调试器暂停，并通知 VS Code 显示当前对应的源码行
配置示例：Node.js 调试 TypeScript
确保 tsconfig.json 开启 source map：
{
"compilerOptions": {
"sourceMap": true,
"outDir": "./dist",
"rootDir": "./src"
}
}
VS Code 的 .vscode/launch.json 配置：
{
"type": "node",
"request": "launch",
"name": "Launch with Source Map",
"program": "${workspaceFolder}/src/index.ts",
"outFiles": ["${workspaceFolder}/dist/**/*.js"],
"resolveSourceMap": true
}
这里 outFiles 告诉调试器生成的 JS 文件路径，VS Code 会自动查找对应的 source map 并建立连接。
常见问题与注意事项
-
sourceMap 必须正确生成：编译工具要输出有效的 map 文件，且
sourceMappingURL正确指向它 -
路径映射要匹配：map 文件里记录的源文件路径必须能被 VS Code 找到，否则无法显示源码。可通过
webRoot或sourceRoot调整 - 生产环境慎用：发布时通常不上传 source map，避免暴露源码
- 浏览器调试同理：Chrome 调试前端代码也依赖 source map，机制类似
基本上就这些。只要配置好生成环节和 launch.json，VS Code 就能“透明”地在原始代码上调试，即使实际运行的是转换后的 JavaScript。
