Sourcemap

约 675 字大约 2 分钟

2026-02-11

在构建后的代码里调试线上错误，最怕看到“压缩后第 1 行第 99999 列”。

Source Map 的价值就是：把“构建后代码位置”映射回“源码位置”，让错误定位和调试回到人类可读的层级。

为什么需要 Source Map

它主要解决三类问题：

开发时快速定位报错位置（含经过 Loader/编译后的代码）。
线上错误上报平台（如 Sentry）还原源码堆栈。
团队排查问题时减少“看打包产物”的时间浪费。

`devtool` 的本质

devtool 不是“开或关 map”这么简单，它同时影响：

构建速度。
映射精度（行/列，是否包含 Loader 前后映射）。
产物安全性（是否暴露源码）。

配置	构建速度	定位精度	典型用途
`eval-cheap-module-source-map`	快	行级，含模块映射	本地开发首选
`source-map`	慢	行+列，精度高	生产排障
`hidden-source-map`	中	行+列，精度高	生产上报（不暴露引用）
`nosources-source-map`	中	有栈信息，无源码内容	安全要求较高场景
`false`	最快	无	对调试无需求的极简场景

常见 devtool 选型

开发与生产推荐策略

思路不是“一套通吃”，而是按目标区分：

开发：优先反馈速度 + 足够调试体验。
生产：优先可观测性 + 安全边界。

// webpack.dev.cjs
module.exports = {
  mode: 'development',
  // 开发阶段构建速度优先
  devtool: 'eval-cheap-module-source-map',
};

// webpack.prod.cjs
module.exports = {
  mode: 'production',
  // 线上建议根据错误监控平台选择 source-map 或 hidden-source-map
  devtool: 'hidden-source-map',
};

与错误监控平台的配合

只生成 map 还不够，真正线上可用还要做两件事：

上传 Source Map 到监控平台。
产物和 map 版本严格对应（通常用构建版本号或 commit hash 关联）。

警告

如果产物和 map 版本不一致，错误堆栈会“能解析但解析错位”，比没有 map 更难查。

使用注意事项

建议

本地开发固定 eval-cheap-module-source-map，保持团队一致。
生产优先 hidden-source-map，配合监控平台上传。
map 文件单独控制访问权限，不随静态资源完全公开。

常见误区

最佳实践

明确“开发调试”和“生产排障”是两套目标。
在 CI 中自动化上传 Source Map，避免手动漏传。
给发布流程增加“产物与 map 一致性”校验。