AI 摘要：本文系统解析了 JavaScript 中 Source Map 的内部机制，从 TypeScript 构建流水线到 Source Map 的 JSON 结构与 Base64 VLQ 编码，作者逐步展示了浏览器如何通过这些映射信息，将压缩后的生产代码还原回开发者可读的源文件位置。

1. 引言：Source Map 的作用
• 解释 Source Map 如何连接构建后的 “生产代码” 与原始源文件
• 举例说明浏览器在 DevTools 中如何利用 Source Map 还原源码位置

2. TypeScript 构建管线（Build Pipeline）
• 概述现代 JavaScript 构建的三个阶段：转译 (Transpilation)、打包 (Bundling)、压缩 (Minification)
• 展示原始 TypeScript 源文件示例（add.ts / fibonacci.ts / main.ts）
• 强调每个阶段 Source Map 保持了源代码映射关系

3. Source Map 文件结构
• Source Map 为 JSON 格式，通常以 .js.map 结尾
• 字段详解：
• version：版本号（通常为 3）
• file：对应的生成后文件名
• sourceRoot：源文件路径前缀
• sources / sourcesContent：原始文件路径和内容
• names：标识符数组（变量与函数名）
• mappings：压缩映射字符串（核心内容）
• 指出 mappings 字段使用 VLQ 编码进行空间压缩

4. 理解映射机制：VLQ 编码 (Variable Length Quantity)
• mappings 字符串由逗号与分号组成，分号分行、逗号分列表示段（segment）
• 三种 segment 格式：
• 单值：仅表示生成列位置
• 四值：完整的源映射
• 五值：包含原始名称索引（变量或函数重命名时使用）
• 说明相对位置编码（delta encoding）原理——通过存储偏移量而非绝对位置实现高压缩率

5. VLQ 编码的工作原理
• 每个数字通过以下步骤编码为 Base64：
1. 编码符号位（sign bit）区分正负数
2. 拆分成 5 位数据块+1 位延续标志 (continuation bit)
3. 使用 Base64 字符表映射（A–Z, a–z, 0–9, +, /）
• 举例说明数字 7 如何被编码为 “O”
• 总结其节省空间与高效解析的优点

6. 实例解读与调试意义
• 通过 add.js.map 的 decode 过程展示行列映射
• 演示如何由压缩代码精确反查到原始 TS 源文件行列
• 强调 Source Map 在前端调试、错误定位和代码回溯中的核心地位

Do more with less. | Polar Signals

The Inner Workings of JavaScript Source Maps

A deep dive into how JavaScript source maps work under the hood, with examples showing how all the pieces fit together.