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 文件单独控制访问权限,不随静态资源完全公开。
常见误区
- 生产直接用
eval系列配置。 - 打开
source-map却不上传 map,导致线上无收益。 - 版本发布后未清理旧 map,增加运维混乱。
最佳实践
- 明确“开发调试”和“生产排障”是两套目标。
- 在 CI 中自动化上传 Source Map,避免手动漏传。
- 给发布流程增加“产物与 map 一致性”校验。
