结论先行:线上 JS 经过压缩混淆,报错堆栈只有 a.b.js:1:23456 这类无意义坐标;source map 是还原现场的唯一钥匙。生产环境推荐「hidden source map」策略——构建时生成 map 但不写入 sourceMappingURL、不随静态资源公开发布,而是上传到错误监控平台,兼顾可定位与不泄露源码。 本文给出 Vite 配置、上传流程与错误定位实战。
source map 的三种发布策略
| 策略 | Vite 配置 | 产物行为 | 适用 |
|---|---|---|---|
| 公开 map | build.sourcemap: true | 生成 map 且 JS 末尾带 sourceMappingURL | 内部系统、开源项目 |
| 隐藏 map | build.sourcemap: 'hidden' | 生成 map 但不写引用注释 | 生产环境推荐 |
| 不生成 | build.sourcemap: false | 无 map | 无法定位,不建议 |
hidden 的关键在于:浏览器默认不会去拉取 map(没有引用注释),但监控平台拿到 map 文件后仍可完成堆栈还原。也可用 SourceMap 响应头把 map 位置告知可信工具,具体以平台文档为准。选择策略时还要考虑团队排障习惯:如果经常需要在生产浏览器 DevTools 里直接断点调试,公开 map 的内部系统更顺手;面向公网用户的产品则一律 hidden,把还原能力收敛到监控平台内部。
Vite 配置与上传流程
export default {
build: {
sourcemap: 'hidden',
},
};CI 中构建完成后,把 dist 下所有 .map 上传到监控平台,再从发布产物中删除。以 Sentry 为例:
sentry-cli releases new '$VERSION'
sentry-cli releases files '$VERSION' upload-sourcemaps dist --url-prefix '~/assets'
sentry-cli releases finalize '$VERSION'
find dist -name '*.map' -delete三个要点:release 版本号必须与前端 SDK 初始化时传入的 release 一致;url-prefix 要与线上资源实际路径对应,否则堆栈匹配不上;上传成功后务必删除 map 再部署,并确认 CDN 没有缓存旧 map。map 文件与构建产物一一对应,任何「构建后再次压缩」的操作都会让 map 失效。
错误定位实战
接入监控 SDK 后,一条典型线上错误的还原链路是:捕获异常 → 上报压缩堆栈与 release/dist 标识 → 平台用对应 map 反解出源文件、行号、列号乃至原始变量名。落地时注意四类问题:其一,跨域脚本需加 crossorigin 属性且 CDN 返回 CORS 头,否则只能拿到 Script error;其二,异步 chunk 的 map 也要上传,漏传会导致部分页面无法还原;其三,采样率与去重策略要配置,避免同一个死循环错误刷爆配额;其四,给错误打业务标签(页面、接口、用户分群),排障效率远高于裸堆栈。
业务错误与异常的分流
不是所有「错误」都该进异常监控。接口返回的业务失败(库存不足、优惠券过期)属于预期分支,应走业务埋点而非 error 上报。这里能体现统一返回结构的价值:api工厂 SDK 的所有接口统一返回 {code,data,msg}(https://www.it120.cc/sdk/index.html),前端封装层可以按 code 一刀切分流——code 非 0 走业务提示与埋点,网络异常与 JS 运行时错误才进监控平台,告警噪音大幅下降。接口行为可先在官方 Playground(https://www.it120.cc/playground.html)验证,再决定各类 code 的处理策略,避免把平台正常返回误当异常上报。
监控指标与告警治理
接上监控只是起点,指标设计决定它有没有用。建议盯四个数:错误率(出错会话/总会话,比绝对条数更能反映影响面)、新增错误(按 release 对比,新版本引入的错误要第一时间暴露)、影响用户数(同一错误去重后的触达规模)、还原成功率(堆栈能否反解,低于预期说明 map 上传有缺口)。告警按「新增 + 影响面」触发,而不是按条数,避免老错误反复打扰;每个告警指定认领人,修复后在平台标记 resolved 并关联 release,形成闭环。发布后 30 分钟是黄金观察期,把错误率曲线与发布事件对齐展示,回滚决策会果断得多。
安全与合规注意
source map 包含完整源码与目录结构,公开暴露等于开源未授权代码,还可能泄露内部接口路径与注释中的敏感信息。上线前用 curl 抽查线上 .map 是否 404;监控平台的 map 访问权限按团队收敛;离职与外包场景下及时轮换上传令牌。若产品面向多端,小程序端的 map 策略与 Web 不同,按各端监控方案分别处理。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。