HUA

在现代前端开发中，源码通常需要经过打包、压缩、转译等多个构建步骤，最终输出的 JavaScript 代码往往与原始代码相去甚远。这虽然对性能有利，却带来了一个问题：调试困难。

为了解决这个问题，浏览器引入了 Source Map 技术，可以将压缩或转译后的代码映射回原始源代码。本文将深入介绍 source map 的原理、文件结构、编码方式，并通过一个实际例子进行详细分析，甚至手动解码其中关键字段。

一、什么是 Source Map？

Source Map 是一种 映射文件格式，用于建立“编译后代码”与“原始源代码”之间的对应关系。借助它，浏览器可以将压缩、合并、转译后的 JS 还原回我们熟悉的 TypeScript、ES6+、Vue 或 JSX 等原始源码。

主要用途

  • 让调试工具显示源码而非压缩后的代码
  • 支持断点、变量查看、调用栈追踪等调试功能
  • 保留开发体验，同时不牺牲生产代码性能

二、Source Map 文件结构概览

一个典型的 source map 文件是一个 JSON 格式的 .map 文件，结构大致如下：

 1{
 2  "version": 3,
 3  "file": "example.min.js",
 4  "sources": ["../example.js"],
 5  "sourcesContent": ["function add(a, b) {\n  return a + b;\n}\n\nconsole.log(add(2, 3));"],
 6  "names": ["add", "a", "b", "console", "log"],
 7  "mappings": "AAAA,SAASA,IAAI,CAACC,CAAC,EAAEC,CAAC,CACnB,OAAOD,CAAC,GAAGC,CAAC,CAAC,CAAC,CAClB,EAAEC,OAAOC,IAAI,CAACH,GAAG,CAAC,CAAC"
 8}

字段说明

字段名含义
versionSource map 格式版本（目前固定为 3）
file对应的输出文件（通常是压缩后的 JS 文件）
sources映射所依赖的源文件路径数组（可多个）
sourcesContent源文件的完整内容（用于 DevTools 显示）
names映射中使用到的变量、函数、方法名
mappings最核心字段：记录每段代码的位置映射，采用 VLQ 编码

三、Source Map 的工作原理

调试工具（如 Chrome DevTools）的工作流程大致如下：

  1. 浏览器加载 JS 文件
  2. 检测末尾是否存在 //# sourceMappingURL=xxx.map 注释
  3. 解析 .map 文件，获取 mappings 信息
  4. 将编译/压缩后的代码定位映射到 sources 和 sourcesContent 提供的原始代码
  5. 实现调试器中源码展示、断点调试、堆栈还原等功能

四、实际示例：JS 文件生成 Source Map

示例源码：example.js

 1function add(a, b) {
 2  return a + b;
 3}
 4
 5console.log(add(2, 3));

使用 esbuild 对其压缩并生成 source map：

 1esbuild example.js --minify --sourcemap --outfile=dist/example.min.js

生成两个文件：

  • example.min.js
  • example.min.js.map

压缩后代码：

 1function add(n,d){return n+d}console.log(add(2,3));
 2

五、mappings 字段详解

mappings 是 source map 中最复杂的字段，它采用VLQ（Variable-Length Quantity）编码来压缩大量的位置信息，确保文件体积小、解析速度快。

mappings 的结构

  • 使用 ; 分隔 目标文件中的行
  • 每行中使用 , 分隔不同片段（segment）
  • 每个 segment 使用 VLQ 编码，表示源文件中对应的行列信息

segment 的含义（最多五个字段）：

字段序号含义
1生成代码中的列号（相对于前一个 segment）
2源文件索引（对应 sources 数组下标）
3源文件行号（相对上一个 segment）
4源文件列号（相对上一个 segment）
5（可选）变量名索引（在 names 中的位置）

六、进阶解析：手动解码 mappings 字段

示例 segment：AAAA

 1A = base64 0 → VLQ 解码值 0
 2A = 0
 3A = 0
 4A = 0

解码结果：[0, 0, 0, 0]

表示：

  • 压缩文件第 0 行第 0 列
  • 源文件 ../example.js（索引 0）
  • 源文件第 0 行第 0 列
  • 没有变量名索引

示例 segment：CAAC

 1C = 2 → +1
 2A = 0
 3A = 0
 4C = 2 → +1

相对于前一个 segment [0, 0, 0, 0]，此段表示：

  • 目标代码列 +1 → 第 1 列
  • 源文件索引不变
  • 源文件行不变
  • 源文件列 +1

七、Source Map 的类型

类型描述
External.js 文件末尾有注释，指向 .map 文件（最常见）
Inline将 source map 用 base64 内嵌进 JS 文件
Hidden生成 map 文件但不加入注释，适合线上调试
Eval开发时使用 eval() 动态生成源码映射，用于热更新等

八、辅助工具推荐

九、常见问题

Source Map 会暴露源码吗？

是的。建议：

  • 不在生产环境部署 .map 文件
  • 或配置访问权限
  • 或使用 hidden 类型

浏览器没加载 Source Map 的原因？

  • 没有 sourceMappingURL 注释
  • .map 文件路径错误或未部署
  • DevTools 设置未开启 Source Map

十、总结

内容描述
什么是 Source Map编译后代码和源码的映射表
mappings 字段使用 VLQ 编码压缩位置关系
手动解码可用于插件开发和调试排错
生产部署建议谨慎暴露 .map 文件
实用工具Chrome DevTools、可视化工具等
个人笔记记录 2021 ~ 2025