一直觉得前端监控这事有点像买保险——没出事儿的时候觉得浪费钱一上线就出事才发现当初怎么没多看两眼。我经历过不止一次线上白屏、按钮点了没反应、用户截图糊了一脸但自己本地跑得好好的情况那会儿根本没有监控系统全靠用户反馈才知道出了问题被动到怀疑人生。所以后来有机会从零搭一套前端监控的时候我做了比较完整的方案设计覆盖了错误报告、版本回滚两个核心方向今天就把整个设计过程、踩过的坑和最终落地的方案完整写出来。这套东西可能听起来复杂但核心思路其实就三句话把线上用户的报错收集回来把错误定位到具体代码版本出问题能快速回滚止损。适合正在做中大型前端项目、遇到过线上问题难以排查的团队也适合打算从零搭建监控体系但不知道从哪下手的同学参考。1. 监控系统的整体设计与思路拆解1.1 先搞清楚监控要解决什么设计任何系统之前最忌讳的就是一上来就写代码。你得先想明白一件事这套监控到底是给谁用的解决什么痛点。我当时的处境是项目用户量不算小线上偶尔会出问题但问题出现的时机和用户的操作路径完全不可控。测试环境永远测不出真实用户环境的问题——网络慢、浏览器版本旧、机型性能差、用户乱点一通这些场景测试同学复现不了本地开发更是无从下手。所以监控系统要解决的第一件事是错误发现。让线上报错从用户截图反馈变成系统主动上报把发现问题的时间从用户忍不了才说提前到错误发生的那一刻。第二件事是错误定位。不光是知道报错了还要知道错在哪一行代码、哪个页面路由、用户的什么操作触发了它这需要收集足够多的上下文信息。第三件事是快速恢复。错误定位之后如果确认是最近一次发布引入的问题能不能一键回滚到上一个稳定版本把用户影响控制在最短时间窗口内。这三件事对应到技术方案上就是错误采集、数据上报、版本管理三个模块。它们之间是递进关系没有采集监控就是空中楼阁没有上报采集的数据只能在用户浏览器里躺着没有版本管理定位到问题了也无法快速止损。1.2 自研还是用现成监控方案这是一个绕不开的问题。市面上的监控平台不少比如国内的付费商业方案、开源的Sentry都是成熟的选择。我当时也纠结过最后选了自研原因是多方面的。现成方案的优势很明显部署简单、开箱即用、功能全面Sentry甚至自带sourcemap还原、告警通知、版本关联这些高级能力。但问题也很现实首先数据安全。监控数据里会带用户路径、业务参数这些信息外服和私有化部署的成本都不低。其次定制化受限。我想在错误上报里附加自己的业务标签、想自定义告警规则、想把回滚流程和内部发布系统打通用现成方案要么做不到要么得绕很远。最后成本。用户量大了以后商业方案按量计费是一笔不小的开销。但自研也不是什么都自己写。我的做法是核心链路自研周边能力复用错误采集、上报SDK、版本标记、回滚开关自己写告警通知接的是内部IM机器人日志存储用了现成的日志服务sourcemap还原工具参考了开源实现。这样既保住了定制化空间又不用在每个轮子上都重复造一遍。注意如果你的团队就三五个人、项目周期紧、对数据合规没有硬性要求直接用成熟的商业方案或者开源Sentry性价比反而更高。自研监控是个持续投入的活不是上线就完事后面还有数不清的告警规则要调、误报要过滤、新浏览器兼容要适配。一定要想清楚自己是否真的需要。1.3 整体数据链路设计监控系统的数据链路可以用一条线串起来浏览器端采集 → 本地聚合 → 批量上报 → 服务端接收 → 数据存储 → 分析展示 → 告警通知 → 触发回滚。每一环都有自己要解决的问题。浏览器端是数据源头要解决的是怎么把错误不漏不重地抓到包括JS运行时错误、Promise未捕获异常、资源加载失败、框架生命周期里的错误。本地聚合是为了减少网络请求把短时间内的多条错误合并成一批发送避免用户网络被频繁上报请求拖垮。批量上报要解决的是怎么保证数据尽可能送达这里要考虑网络断线、页面关闭、请求失败重试等场景。服务端接收相对简单一个HTTP接口就够了但要做参数校验、频率限制、数据清洗。存储层要看数据量小项目直接写数据库按天分表就行量大就得考虑链路追踪和分布式日志的架构。分析展示是给开发者看的核心诉求是错误列表、错误详情、趋势曲线、版本对比。告警通知负责在错误量超过阈值时第一时间找到人。回滚机制则是最后一道防线确认是发布引入的问题后一键回到上一个稳定版本。我画过一条消息流转的示意图从浏览器到展示层是实时的从分析到回滚是半自动的——告警触发人可以介入确认不搞全自动回滚避免误判导致更大的事故。后面会专门讲这一点。2. 错误报告模块采集端的核心实现2.1 四种错误类型的捕获方式前端错误从来源上分大致有四类JS运行时错误、Promise异常、资源加载错误、框架层错误。每一类的捕获手段都不一样需要分开处理。JS运行时错误用window.addEventListener(error)捕获注意这里不要用window.onerror直接赋值因为后续可能还有其他模块也要监听error事件用addEventListener更安全。回调里能拿到错误信息、出错的文件、行号、列号以及完整的error对象。这里有个关键点脚本错误如果是跨域的浏览器默认只报告Script error.拿不到具体堆栈需要在给静态资源加crossoriginanonymous属性的同时让静态资源服务器返回Access-Control-Allow-Origin响应头才能拿到真实的错误信息。Promise异常用window.addEventListener(unhandledrejection)捕获。这个坑特别多很多开发者写promise.catch()时漏掉了某些分支或者用async/await时忘了包try/catch一旦发生异常错误不会抛给全局的error事件而是触发unhandledrejection。我见过不少项目只监听error事件结果Promise类的报错全部漏掉监控数据看着一片祥和实际线上已经炸了。资源加载错误也走error事件但需要判断event.target区分一下是不是window本身。脚本、图片、样式、字体等资源加载失败时会触发目标元素上的error事件但不冒泡到window。所以要用捕获阶段监听window.addEventListener(error, handler, true)第三个参数传true。捕获阶段先在父节点走一遍能拦截到子元素的加载错误。框架层错误比较特殊。React可以用ErrorBoundary错误边界捕获组件渲染生命周期里的错误Vue则提供了app.config.errorHandler全局错误处理器。这些框架钩子捕获的是框架内部执行阶段的错误和原生事件捕获是互补关系两套都要接才能做到全覆盖。2.2 错误标准化与上下文信息采集采集到错误只是第一步更关键的是把错误格式化成统一的JSON结构保证后续存储和分析都基于同一种数据模型。我定义的标准错误结构大概长这样{ type: javascript, // 错误类型javascript | promise | resource | framework | http message: Cannot read property of undefined, stack: at xxx (app.js:102:15), filename: https://cdn.example.com/js/app.8f3k2d.js, lineno: 102, colno: 15, pageUrl: https://example.com/user/profile, route: /user/profile, // 前端路由路径 userId: u_1024, // 可选业务用户标识 project: web-console, version: 2.5.0, // 应用版本号 releaseId: rls_20240615_01,// 发布标识关联发布系统 deviceInfo: { ua: Mozilla/5.0 ..., os: macOS, deviceType: desktop, browser: Chrome, browserVersion: 126.0 }, timestamp: 1718409600000, extra: {} // 自定义扩展字段 }这里面有几个字段是需要特别说一下的。route字段不是简单用window.location.href而是从路由实例里取当前的路由路径。因为单页应用里用户跳来跳去hash和history模式都可能变从框架路由里取是最准确的。userId是可选的涉及用户隐私我建议默认不采集只在特定场景下通过开关开启。加了用户ID对排查单用户问题帮助极大但要有合适的隐私合规评估。version和releaseId是版本回滚的核心关联字段后面专门讲。deviceInfo不建议自己写正则解析UA维护成本很高直接用现成的ua-parser-js或者内置的navigator.userAgentData。我早期自己写了一套正则结果每年浏览器更新都会出幺蛾子后来老老实实换成了开源库。上下文信息还包括用户的操作路径这个可以简单实现把用户最近点击的元素或者触发的路由变化记录在一个定长数组里出错误时一起上报。不一定要做全量的用户行为录制那种成本太高了记录最近10~20个关键操作就足够还原现场。2.3 性能数据要不要一起采集错误监控之外我当时顺手把性能监控也做了不是因为贪多而是因为很多错误本质上是由性能问题引起的。比如首屏加载过慢导致用户反复点击接口长时间pending导致前端超时这些在错误监控里未必有体现但用户的体验已经在崩溃边缘。性能数据核心采集这几个First Paint、First Contentful Paint、Largest Contentful Paint以及资源加载耗时。用PerformanceObserver可以拿到代码量不大const observer new PerformanceObserver((list) { for (const entry of list.getEntries()) { // 记录 performanceEntry.name 和 entry.startTime / duration } }); observer.observe({ entryTypes: [paint, largest-contentful-paint] });此外还要关注接口请求的耗时和失败率。前端发起的HTTP请求用一个统一封装的请求库包一层成功和失败的耗时都记录一条指标和错误数据走同一条上报通道。这样线上出现接口大面积变慢或者某个接口成功率暴跌时能第一时间发现。性能和错误共用一条数据管道有几个好处一是SDK只需要维护一套上报逻辑二是分析的时候可以把同一个时间点的性能趋势和错误趋势叠加起来看比如新增错误数在飙升同时首屏耗时也在恶化那基本可以判断是同一根因比如某个依赖资源挂了导致的。3. 上报策略与可靠性保障3.1 批量上报与数据合并策略错误数据如果每发生一条就发一个请求用户网络会被疯狂消耗。尤其错误经常是连续爆发的——某个脚本一挂可能一瞬间就触发几十条错误。所以上报SDK一定要做批量合并。我实现了一个简单的上报队列内部维护一个数组push进去的错误先缓存然后设定一个定时器每5秒或者队列长度达到20条时触发一次上报把数组里所有数据打包成一个数组发出去。同时还有一个变量记录队列是否正在上报中避免并发导致数据乱序。合并的时候要注意不是所有错误都适合合并成一条。比如几条错误堆栈完全一样、发生在同一路由、只是时间略有差异这大概率是同一个Bug被多个用户触发应该合并成一条错误聚合记录附带一个count字段。但如果错误堆栈不同即便是同批次也要保留多条原始数据。服务端在做聚合分析的时候我会在写入存储前先做一次错误指纹去重。指纹的算法很简单message filename lineno colno拼起来做哈希。高度相似的错误用指纹归组展示的时候就按指纹分组每条错误记录展示最近一次发生时间和累计次数点开才能看到每一次的完整信息。这个设计对错误列表页面的可读性提升非常大不然同一个错刷几十行根本没法看。3.2 sendBeacon、请求失败与断网缓存上报请求和普通业务请求不一样它发生在页面可能即将关闭、网络可能不稳定的场景。传统的XMLHttpRequest在这些场景下很不靠谱页面一卸载请求就被中断了。navigator.sendBeacon()是专门为这种场景设计的它会在页面卸载时把数据异步发送到服务器不阻塞页面关闭而且不受传统XHR在unload阶段被取消的限制。但sendBeacon也不是万能的。一是它有请求体大小限制一般2MB左右各浏览器不完全一样二是部分老浏览器不支持三是你没法拿到响应做后续处理。所以我的策略是优先使用sendBeacon不支持或者数据量超过上限时降级为fetch或Image上报。用Image兜底是因为它是一个1像素的GET请求跨域限制少但只能传少量数据需要把错误信息压到URL参数里适合极端降级场景。断网是另一个容易忽略的问题。移动端用户可能在地铁里、电梯里网络信号不稳定错误上报时请求发不出去就直接丢了。我的做法是给上报队列加一个localStorage持久化缓存。上报失败时把数据写入localStorage下次页面加载时先检查缓存里有没有未上报的数据有就补报。localStorage的容量有限要注意控制缓存数据量。我加的容量上限大概150KB超过后丢弃最早的数据——毕竟监控数据丢了可以补用户本地存储被打爆那就是新的事故了。缓存还要做版本号隔离SDK升级之后旧的缓存数据格式可能不兼容解析失败要能安全跳过。3.3 服务端接口设计与数据采样服务端的接收接口设计上要考虑几个点。首先是验签和防刷监控上报接口是公开的理论上任何人都可以往你的接口伪造数据。我加了一个简单的token校验SDK初始化时从配置下发一个上报token请求时放在header里服务端校验。加不了多强的防护但能过滤掉绝大多数误报和恶意请求。接口响应要快不能做过多耗时操作。我是上报接口直接返回200把数据先推入消息队列再由消费者异步写入存储。这样上报接口的P99响应时间可以压在50ms以内不会对线上用户造成额外负担。数据采样的策略也很重要。用户量小的时候全量采集没问题但PV过亿的项目全量采集的成本非常惊人。采样可以分两种随机采样适合性能数据比如只采集10%用户的数据全量采集适合错误数据因为错误是偶发的丢了就没了。如果错误量也大比如某个恶意脚本刷量就得用速率限制每条相同指纹的错误每分钟最多上报N条超过N只计数不上报。存储方案我当时用的是内部日志服务按天建索引字段就是上面标准化结构里的那些。查询上支持按项目、版本、路由、错误指纹、时间范围组合筛选展示端画趋势图和错误列表。如果你自研、数据量不大用Elasticsearch单机版就可以起步不必一上来就上分布式日志集群。4. 版本管理与版本回滚机制4.1 监控数据如何关联到具体版本前面反复提到版本这里展开讲。前端项目不是发完就完了代码上线之后你得能回答一个问题当前线上的报错是哪个版本引入的我把版本信息分成了两层。第一层是构建版本号用CI流水线的构建号和Git短哈希拼出来比如2.5.0.build_20240615_3f9ac21构建时通过环境变量注入到应用里SDK初始化时自动读取。第二层是发布标识releaseId发布系统每次发版都会生成一个唯一ID后端把releaseId、版本号、发布时间、发布人、变更内容对应关系记录下来。这样当一条错误上报上来服务端解析错误里的版本号就能反查到这次发布对应哪个releaseId、发布了什么内容、什么时候上的线。配合监控数据的时间线就可以画出一条版本发布时间 vs 错误量变化的对照曲线。这正是判断某个版本是否引入了回归Bug的核心依据。还应该把sourcemap纳入版本管理。错误上报里拿到的堆栈是压缩混淆过的像是t.exports、r(123)[0]这种完全不可读。只有把构建产物对应的sourcemap上传到监控平台才能把压缩代码还原成原始源码。注意sourcemap千万别暴露到线上对用户可访问的目录那等于把源码免费送人souremap应该只上传到监控服务端并且做鉴权访问。4.2 回滚的触发时机与判断逻辑版本回滚不是随便就能滚的要先定义什么情况下需要回滚。我自己的标准是版本上线后30分钟内错误率超过基线前7天同时间段的平均值的3倍且持续超过5分钟就判定为疑似回归。同时在聚合错误详情里如果出现了新的错误指纹即上一版本从未出现过的错误类型那基本可以实锤是本次发布引入的。这里我特别说一句不建议做全自动回滚。自动化的判断逻辑再严谨也有误报的可能。比如大促活动页瞬间涌入的流量本身就会推高错误量或者某个第三方接口挂了导致前端大量报错这并非前端代码回归。真正上线遇到这种情况团队需要的是准确的信息快速的处置通道而不是系统擅自做决定。所以我设计的流程是半自动监控系统识别到异常后自动告警并把疑似回归的证据错误曲线、新增指纹、涉及版本对比推送到工作群当班开发确认后点一个回滚按钮系统自动触发发布系统的回滚接口。人工确认通常只需要几十秒但能避免大量误伤。回滚的技术实现也不是简单地把上一版代码重新发一遍。现在的部署体系一般有两种方案一种是产物版本切换发布系统里保存每次构建的产物包回滚时把CDN的版本引用切回上一版另一种是路由级别的灰度切换通过统一入口配置中心控制某个版本的流量占比直接从100%降到0。后者更灵活可以在不改动代码的情况下快速切流量也是我在项目中更推荐的方式。4.3 灰度发布与监控的配合回滚是最后的手段更好的是不要走到这一步。灰度发布的价值在监控体系里会被放大很多倍。我当时的做法是新版本先发布到10%的流量观察一段时间监控数据和基线版本同期数据对比。错误率没有明显上升、没有新指纹出现再逐步提高流量比例30%、50%、100%。每一档都盯着监控曲线确认一旦异常立即停止放量并回滚。灰度发布的粒度可以做到比整个版本更细。比如用功能开关控制某个新特性的打开这个开关可以按用户维度、按路由维度控制。出问题的时候关掉开关就完成了逻辑层面的回滚不需要重新部署代码影响面控制在单功能范围内。这比整体版本回滚精细得多。监控数据在灰度过程中的作用是决策依据每个放量阶段都要能回答当前在线上跑的这个版本和基准版本相比错误率、体验指标比如FCP、LCP、接口失败率是不是在可接受范围内。所以监控面板上我会放一个版本对比视图拉出两个版本在上述指标上的曲线一个图表就说明问题比翻半天日志高效得多。5. 常见问题与排查技巧实录5.1 上报数据丢失的排查监控上线后第一个容易踩的坑就是数据上报丢失。明明代码里埋了上报点后台却查不到数据。这类问题我总结了几个最常见的排查方向。先看浏览器控制台有没有报错。很多情况是SDK的token没正确注入接口返回403数据被服务端拒了。再看上报请求是不是被广告拦截插件拦了部分拦截插件会拦掉包含monitor、track、report关键字的URL所以上报路径的命名要尽量中性我后来把上报路径改成了中性的/collect。还有一个隐蔽的问题HTTP和HTTPS混用。如果页面是HTTPS的但上报地址配成了HTTP浏览器会直接拦截请求混合内容拦截。这个在排查的时候特别容易被忽视因为本地开发环境可能一切正常上线后数据全没了。我的经验是SDK初始化时可以对上报地址做一次协议修正以当前页面协议为准避免静态配置写死。5.2 监控SDK自身导致的错误监控代码也是代码也会出错而且监控代码出错时如果处理不当会对业务造成二次污染。我踩过最深刻的一个坑是监控SDK的某个插件在低版本安卓WebView上抛了一个异常结果这个异常又触发了一次错误上报上报逻辑里又抛异常形成死循环直接把用户的页面卡死。修复方案是给整个采集流程的最外层包了大型try/catch并且在SDK内部维护一个自毁开关同一错误被监控SDK自身抛出超过3次就自动禁用监控功能保证监控绝不影响业务。另外一个容易被忽略的问题是性能损耗。我在SDK里对上报队列做了requestIdleCallback调度优先让浏览器的空闲时间段执行数据打包和序列化避免监控代码抢主线程资源。尤其是低端机上频繁的JSON序列化和数据结构复制会直接影响页面流畅度所以给每个采集点都做了节流和采样一次事件循环里最多处理N条数据超出就丢到下一帧再说。5.3 告警风暴与噪音过滤告警也是个大坑。最初我的告警规则很简单错误率超过阈值就告警。结果每晚都收到几十条告警同事群被刷屏后来大家直接把告警群静音了——告警系统彻底失效。解决告警噪音我做了三件事。第一错误分级。新的错误指纹第一次出现属于P2级确认是影响面大的崩溃类错误升为P1只对P1和部分P2告警。第二错误指纹维护了一个已知噪音列表。比如用户主动断网、跨域Script error、广告插件注入导致的白屏误报这些进列表的错误只计数不告警。第三告警聚合。相同指纹的错误在一个告警窗口内只发一条通知附带上发生次数和增速。还有一条经验告警阈值不要用绝对值要用相对基线。某个页面平时的错误率就比其他页面高比如老机型兼容性差用统一的绝对值阈值会导致高发页面永远告警、低发页面永远不告警。用相对于过去7天同时段的倍数作为阈值能自动适配每个页面的正常水位。5.4 定位压缩代码错误的技巧遇到压缩混淆后的错误堆栈直接肉眼看是很痛苦的。除了依赖sourcemap自动还原之外我还有一套手动排查的辅助方法。先看错误的filename里的文件名和版本Hash到发布系统的产物列表里找到对应版本直接对照压缩产物用格式化工具展开。有些错误不是代码逻辑问题而是部署链路问题比如文件404了、CSS加载不全了这种情况看一下堆栈里资源文件是否都在CDN上存在往往比分析堆栈本身更快。另外强烈建议Debug环境关掉sourcemap映射到线上的设置但是保留构建日志里的源码文件列表。构建的时候生成一个产物→源码文件的对照表发布到监控服务端。这样即使sourcemap有各种还原不准确的情况你至少能知道某个报错来自src/pages/user/profile.tsx搜索代码范围就小很多。6. 监控体系后续还能怎么扩展6.1 从监控到问题闭环监控系统做到这一步其实已经形成了发现→定位→修复→验证的闭环。但闭环的价值取决于执行效率。我是给每个错误指纹加了一个处理状态字段待处理、处理中、已修复、已忽略。开发收到告警后在监控后台标记状态、指派负责人、关联修复的commit修复上线后系统自动观察该指纹的错误量是否归零。这个状态机看似简单却解决了团队协作里这个错到底有没有人在管的模糊问题。每个回归的重复错误我会把第一次引入的版本、修复的版本、花了多长时间修完这些数据沉淀下来每月统计一次前端线上事故复盘表。哪类错误最容易漏测、哪个模块事故率最高、平均修复耗时是多久这些数据对研发流程改进很有价值。甚至可以进一步和研发管理平台的迭代数据打通直接看到某个迭代上线后的缺陷密度。6.2 离线日志与埋点抽样延伸监控体系稳定之后可以往两个方向延伸。一个是离线日志队列的升级当用户长时间断网、上报长期失败时把数据累计到用户的IndexedDB里恢复网络后一次性补报。这个对弱网区域用户特别重要前提是要控制单用户的数据量上限做好压缩比如用gzip压缩JSON字符串和字段裁剪。另一个方向是用户无感知埋点抽样。不是每个用户都需要全量采集可以按用户ID的哈希值取模采样比如只采集5%用户的完整数据包含完整的操作路径、接口耗时、错误上下文这部分数据用于深度的问题分析其余95%的用户只采集错误数据本身。这样既能保证核心的异常发现能力又能把存储成本和性能损耗控制在合理范围。6.3 一些运营层面的建议最后给几个非技术但很重要的建议。监控后台的访问权限要管控错误详情里可能会包含用户的业务数据非相关人员不应随意查看。数据保留周期也要和业务方对齐有些合规要求下日志类数据只保留特定周期过期要定期清理。告警值班要有轮值机制。监控是工具最终响应的是人。我们团队每周有一个监控值班角色负责处理当周告警、跟进未闭环的错误指纹、周末尤其要盯紧灰度发布窗口的指标变化。没有明确的负责人再好的监控系统也会变成摆设。还有一点不要追求100%的监控覆盖率。JavaScript生态本身很复杂老浏览器兼容、第三方脚本错误、扩展插件干扰等因素导致必然存在一些采集不到或者无法识别的场景。接受这个现实把核心的用户路径、核心的错误类型覆盖好比追求全量的意义大得多。监控的目的是让团队在大部分情况下能快速定位问题、减少用户损失而不是做一个滴水不漏的数据收集器。我个人在实际操作中的体会是监控系统上线的前两周是最难熬的各种误报、漏报、告警风暴会轮番轰炸这个阶段千万要沉住气把噪音列表和告警规则一条条调顺。等系统稳定下来你会明显感觉到线上问题的平均定位时间从小时级压缩到了分钟级。这个变化是监控系统给研发团队最好的回报。