上线后报错别靠用户截图：vibe 项目的线上报错追踪实战

先说清楚一件事：以下示例中的产品与人物均为虚构。待办应用“明日清单”和它的独立开发者陈默都不存在，他们只是用来讲清楚方法的道具。方法本身是真的，故事是编的，数字也没有任何真实来源。

上线那天最常见的错觉，是以为报错会自己找上门。开发时你坐在电脑前，控制台开着，出错立刻能看到；上线后你不在场，出错发生在别人的手机、别人的网络、别人的操作路径上。你唯一能收到的信号，往往是一张截图、一句“打不开了”，或者干脆什么都没有——用户默默卸载，连抱怨都懒得留。

靠用户截图排错有三个硬伤。第一，截图没有上下文：你不知道用户点过什么、停在哪个页面、用的是哪个版本。第二，截图不可复现：你按描述走一遍，流程是通的，因为触发条件可能是某个旧数据、某个时区、某个网络中断的瞬间。第三，截图来得太晚：用户截图时往往已经是第三次失败，前两次的报错早已消失在空气里。等你拿到截图，真正有价值的现场已经被时间冲掉了。

console.log 也一样。它在开发时是显微镜，上线后却是一台没有录像功能的监控：你只有在场的时候才看得到。更糟的是，很多项目上线后还留着大把日志，却没有任何人去翻——日志写进了某个没人看的角落，等于没写。线上报错追踪要解决的根本问题只有一个：出错的那一秒，系统要自动把现场保存下来，送到你能看到的地方，并且整理成你能下手修的样子。

一、先搭捕获层：出错时自动把现场留下来

捕获层是整套方法的基础。它的工作不是“记录所有日志”，而是“在错误发生的瞬间，抓一份足够定位、又不越界的快照”。至少要覆盖三类错误：未捕获的异常、未处理的 Promise 拒绝、以及你自己主动上报的关键业务失败。只抓第一类是不够的——很多线上问题表现为接口返回 500、支付回调超时、数据写了一半，这些不会以异常的形式冒泡，必须在业务代码里显式上报。

一份合格的报错快照包含七样东西：错误信息、堆栈、版本号、当前路由或页面、用户标识（只存内部编号，不要存姓名电话）、发生时间、以及出错前的一小段操作轨迹，也就是面包屑。面包屑最容易被低估：用户点了哪个按钮、调了哪个接口、切了几次页面，这串轨迹往往比堆栈本身更能告诉你“他是怎么走到这一步的”。没有面包屑，你拿到堆栈也只能猜。

但抓得多不等于抓得对。有些东西永远不应该进报错系统：密码、令牌、密钥、完整的请求体、聊天内容、身份证号、银行卡号。这些数据一旦进了第三方报错平台，就等于多了一个泄露面，而且往往违反你自己隐私政策里的承诺。正确做法是在上报之前做清洗：按字段名黑名单过滤，命中就替换成占位符；对长文本做截断；对不确定的字段默认脱敏，宁可少看一点，也不要多看一眼。下面是一段清洗函数的示意：

const SCRUB_KEYS = ["password", "token", "secret", "apiKey",
  "authorization", "cardNumber", "idCard"];

function scrub(obj) {
  if (!obj || typeof obj !== "object") return obj;
  const out = {};
  for (const [key, value] of Object.entries(obj)) {
    if (SCRUB_KEYS.includes(key.toLowerCase())) {
      out[key] = "[REDACTED]";
    } else if (typeof value === "object") {
      out[key] = scrub(value);
    } else if (typeof value === "string" && value.length > 500) {
      out[key] = value.slice(0, 500) + "…[truncated]";
    } else {
      out[key] = value;
    }
  }
  return out;
}

上报端本身也要有自保。报错上报不能因为上报失败而再抛错，不能因为网络抖动而阻塞主流程，更不能在用户手机上无限重试。正确的做法是：上报走异步队列，失败就丢弃并记一个本地计数，绝不在上报失败时弹框打扰用户。一个会把自己变成新 bug 的报错系统，不如没有。

初始化上报器时，把三件事一次写死：当前版本号、运行环境、以及采样开关。版本号是后面所有分组、对比、回滚判断的锚点，没有它，你连“这个错是新版引入的还是老毛病”都说不清。示意如下：

initErrorReporter({
  release: "1.4.2",          // 每次发版必须改
  environment: "production",
  beforeSend: (event) => scrub(event),
  sampleRate: 1.0,           // 致命错误保持全量，见第五节
});

二、分组与指纹：十万条相同报错其实是一个 bug

陈默的“明日清单”上线第一周就收到了上万条报错，面板上密密麻麻，他第一反应是项目要塌了。点开一看才发现，九成报错来自同一个空指针：某个旧版本数据里少了一个字段，列表页一渲染就崩。十万条报错，修一个地方就全灭了——前提是系统把它们归到了一起。

这就是分组的意义。报错面板的第一单位不应该是“一条报错”，而应该是“一种报错”。分组靠的是指纹：从错误类型、出错文件与行号、调用链里最稳定的几帧里提炼出一个标识，相同的标识归为一组。指纹规则要写得保守：取堆栈顶部稳定的帧，忽略内存地址、时间戳、用户编号这些每次都变的东西。

有两条分组禁令必须刻在墙上。第一，绝不能按时间戳或用户分组——那样每个用户、每次发生都会变成独立的一条，分组就失效了。第二，绝不能把所有错误按错误信息全文分组——信息里常带动态内容，比如某个商品编号、某段用户输入，全文一变就被当成新错误，同一个 bug 会碎成几百组。好的做法是先按类型加稳定堆栈分组，再把动态部分做归一化：数字、编号、路径参数统一替换成占位符。

分组做好之后，面板才开始说人话：哪种错误影响人数最多、哪种错误今天第一次出现、哪种错误在某个版本之后突然暴涨。单人开发者每天打开面板，看到的应该是十几组待办，而不是几万条流水账。数量本身不是信息，整理过的数量才是。

三、Source Maps：没有它，堆栈就是一串乱码

前端项目上线时代码通常经过压缩混淆，线上堆栈指向的是压缩后文件的某一行某一列，看起来像天书。Source Maps 就是把压缩代码还原回源码位置的地图。没有它，你知道“某个地方崩了”，但不知道是哪个函数、哪一行；有了它，堆栈直接指向你写过的源代码。

关键在“按版本上传”。每次发版都要把当次构建的 Source Maps 上传到报错平台，并且和版本号严格对应。版本对不上，地图就是错的，还不如没有。很多团队出问题不是没配 Source Maps，而是只配了一次、之后再也没管，新版报错继续用旧地图还原，结果越查越偏。

这里有一个公开与私有的权衡。把 Source Maps 公开放在 CDN 上，任何人都能下载并还原你的源码——对开源项目无所谓，对商业项目就是把实现细节摊开给人看。更稳妥的做法是只把 Source Maps 上传到报错平台的私有存储，不随前端产物公开发布。代价是多一步上传配置，收益是源码不外泄。这个取舍没有标准答案，但必须是有意识的选择，而不是默认把地图扔在公开地址上不管。

另外要留神：Source Maps 上传失败时，构建流程应该报警而不是静默通过。一个“地图缺失的版本”上线后，所有报错都会变成乱码，而你可能要到第一次排查时才发现。把地图上传写进发版检查清单，缺地图的版本不放行。

四、采样与配额：让报错风暴先伤钱包之前停下来

最贵的教训往往来自报错风暴。某个循环里的报错每秒触发几十次，或者某个接口在故障期间对每个请求都报错，一夜之间就能把按量计费的配额烧光。报错系统本身必须有限流：对同一指纹的错误做节流，比如每分钟最多上报固定条数；对上报端做全局速率限制；对循环触发的错误做去重合并。

采样不是一刀切。合理的策略是分级：致命错误和支付相关错误永远全量，一个都不能丢；高频但无害的已知错误可以采样，比如只上报百分之一；纯展示类的小毛病可以只在新版本的前几天全量，稳定后降采样。分级的前提是你在上报时就打上严重程度标签，而不是事后靠人工一条条挑。

还要给报错系统本身设预算上限：每月配额、每日上限、超限后的降级策略。超限时正确的做法不是停掉所有上报，而是自动降到只报致命错误。最差的策略是毫无上限地全量上报——账单先于修复到来，而你修 bug 的钱已经被报错系统花掉了。

一个实用的经验是：把“报错量突增”本身当作一个需要告警的信号。正常情况下报错量有基线，某个版本发布后报错量翻倍，往往比任何一条具体报错都更早说明问题。下一节讲的告警，正是建立在这个思路上。

五、告警：只对新错误和突增告警，不要对每一次报错告警

对每一次报错都发通知，是最快让人麻木的做法。手机一晚上震几百次之后，开发者会本能地把通知静音——然后真正严重的错误也被一起静音了。告警的原则是：只在需要人立即做判断的时候打扰人。

值得立即告警的有两类。第一类是新错误类型：以前从未出现过的指纹第一次出现，尤其是发布新版本后的一小时内。这类告警的价值在于“早”，它把你从“用户反馈才知道”提前到“上线一小时就知道”。第二类是速率突增：某个已有错误的单位时间发生数超过基线数倍，或者影响用户数突然扩大。这类告警的价值在于“变”，它告诉你某个老问题正在恶化，或者某个外部依赖正在出故障。

告警要带足决策信息：错误类型、影响人数、首次出现时间、关联版本、以及直达面板的链接。一条只有“出错了”的通知等于没通知——收到的人还得自己去翻面板找上下文，黄金时间就浪费在查找上。反过来，告警里也不需要贴完整堆栈，链接过去就能看到。

告警渠道要分层。致命错误走电话或短信级别的强提醒；新错误类型走即时消息；速率突增但未达致命级别的，可以先汇总成日报。分层不是形式主义，它保护的是你的注意力：注意力是单人开发者最稀缺的资源，告警系统的工作是帮你分配它，而不是耗尽它。

六、版本健康：用报错率判断一个版本能不能留

有了按版本分组的数据，就可以做版本健康判断：比较每个版本的报错率——不是报错绝对数量，而是每千次会话或每万次请求里的报错数。新版本用户量小，绝对数量天然偏低，直接比数量会得出“新版很健康”的假结论；按比率比，才能看出真实变化。

上线新版本后的正确姿势是：先看一小时，再看一天。一小时内看新错误类型有没有冒出来、致命错误有没有；一天内看整体报错率相对上一版本是升是降、影响面有没有扩大。设定一个回滚触发线，并且在发版前就写下来：比如致命错误率超过上一版本的数倍，或者支付成功率跌破某个阈值，就回滚，不开会、不犹豫、不“再观察一下”。

回滚触发线之所以要提前写，是因为出问题的时候人最容易自我说服。“可能只是统计波动”“等用户量上来再看”——这些话在凌晨三点听起来都很有道理。提前写好的线，就是用来在那个时候替你做决定的。它不需要多精确，重要的是存在，并且被执行过一次之后你会根据经验把它调得更准。

版本健康还有一个附带好处：它让“这个版本有没有变好”从感觉变成了数据。下次有人问“上次重构到底有没有用”，你不用回忆，直接把两个版本的报错率并排摆出来。数据不会替你做决定，但它会让决定不再靠嗓门大小。

七、单人开发者的每日分诊：十分钟，四个动作

方法再完整，落不到日常节奏里也是空的。对单人开发者，我推荐每天固定十分钟做分诊，四个动作，不多不少。第一，看新增：今天有没有新错误类型，有就先读它，不管它影响人数多不多——新错误是未来的大问题，越早处理成本越低。第二，看突增：哪个老错误的量在涨，涨幅最大的优先。第三，排修复顺序：支付问题最先，登录问题其次，核心流程再次，界面小毛病最后。这个顺序不是按技术难度排，而是按用户损失排：付不了钱的用户会立刻走，界面错位用户还能忍。

第四，维护“已知与忽略”清单。有些错误你暂时修不了，有些是第三方服务抖动，有些是用户旧版本特有、且旧版本用户正在自然减少。把这些错误标记为已知，写上原因和复查日期，到期自动重新提醒。没有到期日的忽略就是永久忽略，而永久忽略迟早会咬你一口。清单的意义不是让你假装问题不存在，而是让你有意识地决定“这个问题本月不处理”，并且到时重新做一次决定。

分诊时还要克制一种冲动：不要一上来就修最有趣的 bug。最有趣的往往不是最要紧的。按损失排序修，修完一个再看下一个。单人开发者的时间表里没有“顺手修一下”的余地，每一次分心都是从核心功能里偷时间。

八、上线前检查清单：发版当天照着打勾

最后是一份可以直接抄的上线前检查清单。第一，报错上报器已初始化，版本号与本次发布一致，环境标记为生产而非测试。第二，清洗规则已启用，敏感字段黑名单已覆盖密码、令牌、密钥，完整请求体不上报。第三，本次构建的 Source Maps 已上传并与版本号对应，上传失败会报警。第四，采样与限流已配置，致命与支付错误全量，高频错误有节流，配额上限与超限降级已设定。第五，告警规则已开启：新错误类型与速率突增会通知到你，通知里带版本与面板链接。第六，回滚触发线已写好，团队里哪怕只有你一个人，也知道跌破哪条线就回滚。第七，分诊节奏已排进日程：每天十分钟，先看新增与突增，再按支付、登录、核心流程、界面的顺序修。

这份清单的每一项都对应前面某一节的坑，单独看都不起眼，合起来就是“上线后不再靠截图过日子”的全部家当。线上报错追踪不是买一个工具就完事，它是一套习惯：捕获时留现场、分组时去噪音、发版时对齐地图、计费时设上限、告警时保注意力、复盘时看版本健康。工具可以换，习惯不能省。

最后回到陈默的“明日清单”——虚构的故事，但结局是每个真实项目都可能遇到的两种结局之一：要么在用户截图里猜谜，要么在自己的面板里按顺序修 bug。区别不在于项目大小，而在于上线那天，你有没有给错误留一条回家的路。