TypeScript sourceMap 配置指南
sourceMap 生成 .map 映射文件，让调试器显示 TS 源码而非编译后的 JS。本文讲解配置、调试体验与生产环境的 sourcemap 策略。
开发环境必开 "sourceMap": true——断点直接打在 .ts 源码上。生产策略：开启生成但不上传公开目录（隐藏式 sourcemap），或上传到错误监控平台后从产物中删除。
没有 sourcemap 的调试之痛
编译后的 JS：变量名变了、async 变状态机、装饰器展开——断点调试如同读汇编。sourcemap 建立编译产物与源码的行列映射，调试器还原原始现场。
开启配置
{
"compilerOptions": {
"sourceMap": true
// "inlineSourceMap": true, // 或内联进 .js 文件
// "sourceRoot": "/src"
}
}
产物旁生成 xxx.js.map，文件尾注释 //# sourceMappingURL=xxx.js.map 引导调试器。
调试体验
- VS Code：launch.json 无需特殊配置——断点直接打 .ts；
- Chrome DevTools：Sources 面板显示原始 TS 文件树；
- Node 错误堆栈：
node --enable-source-maps dist/index.js——堆栈直接指向 TS 行号（生产排障利器）。
生产策略
| 方案 | 做法 |
|---|---|
| 公开 sourcemap | 直接部署（源码对终端用户可见） |
| 隐藏式 | 生成但不上传 CDN，本地存档对应版本 |
| 上传监控平台 | 传观测云/Sentry 后从产物删除——错误堆栈自动还原 |
用真实访问验证前端表现
TypeScript sourceMap 配置指南中的开发期结果，还需要放到真实访问场景中验证。观测云 Web RUM 可采集页面、资源请求和前端错误；应在浏览器入口初始化，并为每次发布设置一致的环境与版本。错误堆栈还原需要上传匹配的 SourceMap，不能仅打开构建选项就认为平台已收到映射文件。
接入文档：Web RUM 接入 · SourceMap 配置。
常见问题（FAQ）
Q：sourcemap 影响运行时性能吗？
不影响执行——纯附加文件。构建时间略增，产物体积增加（可不部署）。
Q：tsx/SWC 的流程需要 sourcemap 吗？
tsx 内置处理；SWC 配 sourceMaps: true——工具链每一环都要透传映射，链条断了堆栈就指向中间产物。
Q：线上错误的堆栈还原？
保留每次发版的 .map 文件存档（按版本归档），或使用自动上传 sourcemap 的错误监控方案——没有 map 的生产堆栈是废铁。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
