一、为什么项目越大，越需要“可排查性”

很多前端同学写功能时只关注“能不能跑通”，但线上问题真正难的部分是：

  • 你不知道错误发生在什么环节
  • 你不知道用户当时做了什么
  • 你不知道请求参数和上下文状态

所以前端工程化里有一个非常重要但常被忽略的目标：
让问题“可复现、可追踪、可定位”。

二、常见错误来源，不只是接口报错

前端线上问题通常可以拆成 4 类：

  1. 运行时错误：Cannot read properties of undefined
  2. 请求错误：超时、4xx/5xx、网关异常
  3. 业务错误：字段缺失、状态流转错误、权限判断不一致
  4. 资源错误：脚本加载失败、静态资源 404、版本缓存不一致

如果日志体系没有分层，这 4 类问题会混在一起，排查效率很低。

三、日志分层：把“信息噪音”变成“可用线索”

推荐把日志分成这 3 层：

1) 行为日志（用户做了什么）

  • 页面进入/退出
  • 点击关键按钮
  • 提交表单

作用：还原用户路径，回答“问题发生前做了什么”。

2) 请求日志（系统调用了什么）

  • 请求 URL、方法、耗时
  • 请求参数摘要、响应码
  • traceId / requestId

作用：定位是前端逻辑问题，还是接口链路问题。

3) 错误日志（哪里失败了）

  • 错误栈（stack）
  • 浏览器信息、设备信息
  • 当前路由、用户 ID（脱敏后）

作用：直接帮助开发定位代码位置和场景。

四、一个最小可用的错误采集思路

在项目里至少做好这三件事：

  1. 全局兜底
    监听 window.onerror 和 unhandledrejection，防止漏采集。

  2. 请求拦截
    在 axios/fetch 封装里统一记录请求耗时和失败信息。

  3. 业务埋点
    在关键流程节点（下单、支付、提交、发布）补业务日志。

这样即使没有复杂平台，也能快速定位大部分线上问题。

五、排查流程建议：先缩小范围，再深入代码

遇到线上 bug，不要第一时间“全局搜索 + 猜”。
更稳的流程是：

  1. 先看错误日志：确定时间、页面、错误栈
  2. 对照行为日志：确认用户操作路径
  3. 再看请求日志：确认是前端问题还是后端问题
  4. 最后回到代码：检查空值、防抖、并发、状态同步

这个顺序的好处是：先用证据缩小范围，再进代码细查。

六、前端项目里最值得优先加的 5 个字段

如果你不知道先埋什么，优先这 5 个：

  • traceId：串起一次完整链路
  • route：错误发生页面
  • userId（脱敏）：关联用户反馈
  • action：用户触发动作
  • duration：接口或操作耗时

这 5 个字段能覆盖大部分排查场景。

七、写在最后

“排查能力”是前端从会写页面到具备工程价值的分水岭。
功能可以靠堆时间写出来，但稳定性和可维护性要靠体系。

当你开始重视日志分层、错误采集和链路追踪时，团队对你的信任会明显提升，因为你不仅会开发，还能兜住线上质量。