Source Map 上传与错误还原

Source Map 解决什么

压缩和转换会改变文件名、行列位置和函数名称。Source Map 使用映射把生产堆栈中的位置还原到原始源码，前提是事件、JavaScript 文件和 Map 属于同一次构建。

真正的关联键通常不只是文件名，还包括发布版本、部署环境、构建标识和资源 URL。重新构建“同一个提交”也可能产生不同产物，因此不要仅靠 Git SHA 猜测对应关系。

生成与分发策略

常见策略包括：

• 生成外部 Map，并让生产文件通过注释公开引用
• 生成 Map 但不在生产文件中引用，即 hidden Source Map
• 只上传到错误监控平台，部署时排除 Map

多数闭源应用会选择 hidden Map 加私有上传，以减少源码被直接发现的机会。但“Source Map 绝不能公开”不是 Web 平台规则；是否公开取决于源码和部署策略。无论采用哪种方式，客户端源码及 Map 都不能包含密钥，Source Map 也不是秘密存储。

推荐发布顺序

构建不可变制品
  → 计算 release / build ID
  → 上传 Source Map
  → 验证上传结果
  → 部署同一份 JavaScript 制品
  → 主动触发测试异常
  → 确认源码还原

上传失败应阻止或至少显著标记发布，不能等到线上事故发生后才发现无法还原。

常见还原失败

• Map 来自另一次构建或另一个环境
• CDN 修改了文件内容、路径或注释
• sourceRoot、资源 URL 或发布前缀不一致
• Monorepo 中多个应用共用了冲突的版本号
• 上传后立即清理，旧版本事件失去对应 Map
• 错误来自浏览器扩展、第三方脚本或动态生成代码

排查时先确认生产事件中的文件 URL 和行列位置，再核对同版本制品摘要，最后检查监控平台的匹配规则。

实践验收

• 在生产模式主动抛出一个测试异常
• 监控平台还原到正确仓库、文件和行列
• 页面不会公开引用私有 Map
• Map 与压缩产物共享不可变发布标识
• 回滚到旧版本后，旧 Map 仍然可用于还原
• 上传内容经过源码、密钥和个人数据检查