Source Maps

什么是 Source Map

Source Map 是一种映射文件，将编译/压缩/转译后的代码（generated code）映射回原始源代码（original source）。它使开发者能够在浏览器 DevTools 中直接调试原始代码（TypeScript、JSX、SCSS 等），而不是面对不可读的产物。

Source Map 文件结构

一个标准的 Source Map（v3 规范）是 JSON 格式文件：

{
  "version": 3,
  "file": "bundle.min.js",
  "sourceRoot": "",
  "sources": ["../src/index.ts", "../src/utils.ts"],
  "sourcesContent": ["original source code..."],
  "names": ["greet", "name", "console"],
  "mappings": "AAAA,SAAS,GAAG;AACZ,..."
}

mappings 字段深度解析

mappings 是 Source Map 的核心，它用一种极度紧凑的编码方式记录了"生成代码中的每个位置对应原始代码的哪个位置"。

结构规则

• 分号 ; 分隔生成代码中的行
• 逗号 , 分隔同一行中的段（segment）
• 每个段包含 1~5 个 VLQ 编码值

每个 segment 的含义（按顺序）

所有数值都是相对值（delta encoding），这使得大部分数字都很小，VLQ 编码后极其紧凑。

VLQ（Variable-Length Quantity）编码原理

VLQ 编码将整数压缩为可变长度的 Base64 字符序列：

1. 每个 Base64 字符代表 6 bits
2. 最高位（第 6 位）是续接位（continuation bit）：1 表示后续还有字符，0 表示当前字符是最后一个
3. 第一个字符的最低位是符号位：0 为正数，1 为负数
4. 数据位按最低有效位优先（LSB first） 排列

编码示例：

数值 0 → Base64 'A' (000000)
数值 1 → Base64 'C' (000010)  → 符号位 0(正), 值 1
数值 -1 → Base64 'D' (000011) → 符号位 1(负), 值 1

"AAAA" 解码为 [0, 0, 0, 0]
→ 生成代码列 0，源文件 0，原始行 0，原始列 0

为什么用 VLQ + 相对编码

如果用绝对值存储每个映射点的行/列号，Source Map 文件会非常庞大。通过两个技巧压缩体积：

1. 相对编码（Delta Encoding）：只存储与前一个值的差值，差值通常很小（0、1、2 等）
2. VLQ：小数字只需 1 个 Base64 字符（6 bits），大数字才需要更多

实际效果：mappings 字段通常只占生成代码体积的 10%~30%。

Webpack devtool 配置选项

Webpack 的 devtool 选项控制 Source Map 的生成方式，不同配置在构建速度和调试精度之间做权衡。

关键修饰词

常用组合速查

开发环境推荐

生产环境推荐

开发环境配置示例

// webpack.config.js
module.exports = {
  mode: 'development',
  devtool: 'eval-cheap-module-source-map',
  // ...
};

Vite 中的 Source Map 配置

// vite.config.js
export default defineConfig({
  build: {
    sourcemap: true,        // boolean | 'inline' | 'hidden'
  },
  css: {
    devSourcemap: true,     // CSS source maps in dev
  },
});

生产环境 Source Map 安全

风险：暴露源代码

如果生产环境部署了 Source Map 文件或在 bundle 中包含 //# sourceMappingURL，任何人都可以通过 DevTools 查看你的完整原始代码，包括：

• 业务逻辑和算法
• API 端点和内部路由结构
• 注释中可能包含的敏感信息

安全策略

策略 1：hidden-source-map + 错误监控上传（推荐）

工作流：

1. 构建时使用 hidden-source-map 生成 .map 文件
2. 在 CI/CD 流水线中将 .map 文件上传到错误监控平台（Sentry / Datadog / Bugsnag）
3. 上传完成后从部署产物中删除所有 .map 文件
4. 部署到生产环境

// webpack.config.js — 生产配置
const SentryWebpackPlugin = require('@sentry/webpack-plugin');

module.exports = {
  mode: 'production',
  devtool: 'hidden-source-map',
  plugins: [
    new SentryWebpackPlugin({
      org: 'your-org',
      project: 'your-project',
      authToken: process.env.SENTRY_AUTH_TOKEN,
      include: './dist',
      urlPrefix: '~/static/js',
      // 上传后自动删除本地 .map 文件
      cleanArtifacts: true,
    }),
  ],
};

策略 2：服务器限制 .map 文件访问

即使部署了 .map 文件，也可以通过服务器配置限制访问：

# Nginx — 禁止公开访问 .map 文件
location ~* \.map$ {
  # 仅允许内网 IP
  allow 10.0.0.0/8;
  deny all;
}

策略 3：nosources-source-map

生成的 Source Map 包含映射信息（行号/列号），但不包含 sourcesContent。这样 Sentry 等工具能定位到文件名和行号，但攻击者无法还原源代码。

适合场景：不想上传 source map 到第三方平台，但仍需基本的错误定位能力

Sentry 集成最佳实践

1. 使用 Release + Commit 关联：每次部署创建 Sentry Release 并关联 Git commit
2. 设置 urlPrefix：确保 Sentry 能正确匹配线上 URL 与 source map 文件路径
3. 版本一致性：bundle 文件和 source map 必须来自同一次构建
4. CI/CD 自动化：在构建流水线中自动上传，避免手动操作遗漏

# 使用 Sentry CLI 上传
sentry-cli releases new "$VERSION"
sentry-cli releases files "$VERSION" upload-sourcemaps ./dist \
  --url-prefix '~/static/js' \
  --rewrite
sentry-cli releases finalize "$VERSION"

# 删除本地 .map 文件
find ./dist -name '*.map' -delete

调试工作流

Chrome DevTools 调试流程

1. 打开 Sources 面板：Cmd+P（Mac）/ Ctrl+P（Windows）快速打开文件
2. 确认 Source Map 生效：在 Sources 面板中应看到原始文件结构（而非 bundle 文件）
3. 设置断点：直接在原始 TypeScript/JSX 代码上设置断点
4. Blackbox 第三方库：右键 → "Add script to ignore list" 避免进入 node_modules 内部

常见问题排查

Source Map 对性能的影响

• 开发环境：source map 生成会影响构建速度（eval 系列最快），但不影响运行时性能
• 生产环境：如果 .map 文件被部署但浏览器不请求（no sourceMappingURL），则零性能影响
• 文件体积：.map 文件通常是 bundle 体积的 2~5 倍；使用 hidden-source-map 时不会影响用户下载体积

面试中如何表达

当被问到"Source Map 是什么"时，可以这样组织回答：

Source Map 是将编译后代码映射回原始源代码的 JSON 文件，基于 v3 规范。其核心是 mappings 字段——通过 VLQ 编码和 delta encoding 将每个生成位置映射到原始文件的行列号，实现了极高的压缩率。

在开发环境中，我通常使用 eval-cheap-module-source-map 来平衡构建速度和调试体验。在生产环境中，使用 hidden-source-map 生成映射文件但不在 bundle 中暴露引用，然后通过 CI 流水线上传到 Sentry，上传后删除本地 .map 文件，既保证了线上错误可追溯，又不暴露源代码。

这样的回答覆盖了原理、实践配置和安全考量三个层面，体现了工程化思维。

Source Map 与错误治理

很多团队把 Source Map 只看成开发调试工具。

这不完整。

在成熟工程里，Source Map 还是错误治理链路的一部分。

原因很简单。

真实线上错误很少发生在你打开 DevTools 的时候。

它们更常出现在：

• 用户设备
• 生产环境构建产物
• 混淆后的堆栈
• CI 已经过了很久之后的某个版本

这时 Source Map 的价值不再是“方便打断点”。

而是：

能不能把一个混淆、压缩、拆包之后的错误，稳定地还原回有意义的源码位置。

这也是为什么现代团队常常把它和 release 管理、commit 关联、错误平台上传放在一起讨论。

如果只会在本地调试场景下理解 Source Map，就会低估它在生产排障中的价值。

一个更成熟的理解应该是：

Source Map 连接的不是“源码和 bundle”这两个文件。

它连接的是：

• 构建系统
• 调试体验
• 线上错误定位
• 发布版本治理

这几条链路一起，才是它在工程里的完整位置。

延展阅读

• Source maps
• Webpack: Devtool
• MDN: JavaScript source map