source map 是将压缩代码错误堆栈精准还原为原始源码位置的核心桥梁；它通过解析 .map 文件中的 mappings 映射关系，将如 main.abc123.js:234:56 的混淆位置转换为 src/api/user.ts:87:12 等可读信息，需前端完整上报错误信息、正确生成并部署 source map，再由服务端按版本匹配解析。
异步函数错误的堆栈往往被截断或缺失关键上下文，单靠浏览器控制台看到的“at Promise.then”之类信息很难回溯到原始调用点。要真正定位问题，必须把压缩后的堆栈还原成源码级位置——Source Map 是实现这一步的核心桥梁。
为什么异步错误堆栈特别难读？
Promise、async/await、setTimeout 回调中的错误，其堆栈通常只包含运行时生成的匿名函数或内部路径，原始文件名、行号、函数名全部丢失。更麻烦的是，Webpack/Vite 打包后代码被压缩混淆，报错显示的 main.abc123.js:234:56 对开发者毫无意义。没有 Source Map，你只能靠猜和试错。
关键：上报完整原始信息
仅捕获错误不够，必须确保上报的数据能支撑后续还原：
- 监听
window.addEventListener('unhandledrejection')和window.onerror，两者缺一不可 - 上报字段至少包括：
message、stack（非event.message）、script（出错脚本 URL）、line、column - 特别注意跨域脚本：若
event.message === 'Script error.'，说明脚本未开启 CORS 或没加crossorigin属性，需前端配合调整资源加载方式
Source Map 必须正确部署并关联
服务端解析的前提是前端能准确告诉它该用哪个 map 文件：
- 构建时开启
devtool: 'source-map'（Webpack）或build.sourcemap: true（Vite），确保生成.map文件 - JS 文件末尾必须有有效注释，如
//# sourceMappingURL=main.abc123.js.map；URL 需可访问且与 JS 同源或配置了 CORS - 服务端按版本号归档 map 文件，错误上报时带上
version字段，避免解析错版本
服务端解析还原才是落地关键
前端上报只是起点，真正把 main.abc123.js:234:56 变成 src/api/user.ts:87:12 是服务端的工作：
- 使用
source-map库（如source-map-support或自研解析器）读取对应 map 文件 - 根据上报的 script URL、行列号，在
mappings字段中反查原始源码位置 - 还原结果应包含：原始文件路径、函数名、行号、列号，例如
at fetchUserInfo (src/api/user.ts:87:12) - 避免将 .map 文件直接放在静态资源目录对外公开，建议通过带鉴权的接口提供，防止源码泄露
