SourceMap 是前端性能监控中还原压缩混淆 JS 错误到原始源码的关键，需确保其正确部署、CORS 配置、sourceMappingURL 路径准确、SDK 显式启用解析，并验证版本匹配与跨域等细节。
SourceMap 能把压缩混淆后的 JS 错误堆栈，映射回原始未编译的源码位置，是前端性能监控中还原真实报错的关键环节。但光有 SourceMap 文件还不够，必须让监控 SDK 正确加载、解析并应用它，才能在错误发生时精准定位到 src/ 目录下的 .ts 或 .js 行列号。
确保 SourceMap 文件可被正确下载
监控平台（如 Sentry、Bugsnag 或自建系统）需要在捕获到错误后，根据报错脚本 URL 自动请求对应的 .map 文件。这要求：
- SourceMap 文件必须部署到线上，并与 JS 文件同域或配置合法 CORS（
Access-Control-Allow-Origin: *或具体域名） - JS 文件末尾需包含有效的
sourceMappingURL注释，例如：//# sourceMappingURL=app.abc123.js.map - 路径必须准确：若 JS 发布在
/static/js/app.js，则sourceMappingURL应为相对路径app.js.map或绝对路径/static/js/app.js.map，不能是本地构建路径（如http://localhost:3000/src/index.ts）
在 SDK 初始化时启用 SourceMap 解析
主流监控 SDK 默认不会自动解析 SourceMap，需显式开启并配置基础信息：
- Sentry：设置
release和dist，并上传 SourceMap 到 Sentry（或配置urlPrefix指向公网可访问的 map 地址） - Bugsnag：通过
sourceMaps选项开启，并确保releaseStage和appVersion与上传的 SourceMap 匹配 - 自研 SDK：需在
onerror或PromiseRejectionEvent捕获后，提取stack中的文件名和行列号，再发起 HTTP 请求获取对应 .map 文件，用source-map库（如new SourceMapConsumer(rawMap)）进行坐标转换
处理常见失败场景
即使配置正确，仍可能因以下原因导致还原失败：
立即学习“Java免费学习笔记（深入）”；
- SourceMap 版本不匹配：线上 JS 与上传的 .map 文件不是同一构建产物，需确保每次发布都生成并上传唯一 release 对应的 map
-
内联 SourceMap 过大：避免使用
devtool: 'inline-source-map'，它会把 base64 编码的 map 嵌入 JS，增大资源体积且不利于 CDN 缓存和独立加载 -
动态加载脚本缺失 map：通过
import()或document.createElement('script')加载的 chunk，其sourceMappingURL也需生效，建议统一用 Webpack 的output.sourceMapFilename控制输出格式 -
跨域限制未放开：浏览器控制台若出现
CORS error while fetching xxx.map，说明服务端未返回正确的跨域头，需后端配合修复
验证还原效果的方法
上线后不要只依赖平台界面显示，应主动验证：
- 手动触发一个已知位置的错误（如在
src/utils/log.ts第 15 行写throw new Error('test')），查看监控后台是否显示该 ts 文件及正确行列号 - 在浏览器开发者工具中，打开
Network面板，过滤.map，确认错误发生后是否成功加载了对应文件 - 使用 sourcemaps.io 在线解析器，粘贴压缩 JS 和对应 .map 内容，检查原始路径和位置映射是否合理
