编程错误大致分六类:语法错误、运行时错误、引用与取值错误、网络与接口错误、逻辑错误、环境与配置错误。 分类的价值不在背名词,而在于每类错误留下的证据不一样——知道它属于哪一类,才知道报 bug 时该附哪段报错、哪个请求、哪张截图。
本文先给一张能直接对照的表,再用八个前端最常见的报错说明"同类不同因"的情况,最后讲一件更实际的事:一条错误要怎么变成一份开发能直接动手的报告。
为什么"错误分类"值得单独讲
多数团队的问题不是不知道 TypeError 是什么意思,而是:
- 把控制台里所有红字都叫 bug,结果一半是第三方脚本和浏览器扩展的噪音;
- 把"页面没反应"直接丢给后端,实际是前端没处理返回结构;
- 报告里只有一句"报错了",开发要先花二十分钟问清楚在哪个页面、哪个浏览器、点了什么。
这三件事都能靠分类解决:类型决定证据,证据决定这份报告能不能被直接修。
六类错误对照表
| 类型 |
什么时候发生 |
典型信息 |
第一手证据在哪 |
| 语法错误 syntax |
代码无法被解析,整段脚本不执行 |
Unexpected token、Unexpected end of input |
控制台第一条红字(之后的报错多半是连锁反应) |
| 运行时错误 runtime |
代码能跑,执行到某一步才失败 |
TypeError、RangeError、Cannot read properties of undefined |
控制台 + 触发它的那一步操作 |
| 引用与取值错误 reference |
用了不存在的变量、字段、模块 |
ReferenceError、x is not defined、undefined is not a function |
控制台 + 页面地址(哪一层路由加载失败) |
| 网络与接口错误 network |
请求失败、被拦截、跨域、超时 |
4xx / 5xx、blocked by CORS policy、net::ERR_ |
Network 面板:请求 URL、状态码、响应头 |
| 逻辑错误 logic |
不报错,但结果不对 |
没有红色信息 |
操作步骤 + 期望结果 vs 实际结果 + 数据样例 |
| 环境与配置错误 environment |
只在某台机器、某个环境、某个账号出现 |
与业务无关的 404、空白页、静态资源加载失败 |
浏览器与系统版本、视口、构建/环境标识、账号权限 |
这张表最有用的是最后一列:它直接告诉你报告里该放什么。 逻辑错误没有报错可截,就必须靠步骤和期望值;网络错误截图没用,必须给请求本身。
语法、运行时、逻辑:边界没有想象中清楚
同一句报错,归到哪一类取决于根因,而不是取决于文字。
Uncaught TypeError: Cannot read properties of undefined (reading 'map') 是运行时错误——代码执行到一个 undefined 上取 .map。但根因可能是:
所以报告里只写"报 TypeError"是不够的,要带上这条数据是从哪个请求来的。这也是为什么控制台报错和失败请求要放在一起看:单看任何一边都会误判。
八个最常见的前端错误
| # |
报错 |
通常意味着 |
该去哪看 |
| 1 |
TypeError: Cannot read properties of undefined |
数据还没到、结构不符、可选链缺失 |
Console + 对应请求的响应 |
| 2 |
ReferenceError: x is not defined |
变量未声明、脚本加载顺序错、打包漏了模块 |
Console + 页面源码里的脚本顺序 |
| 3 |
blocked by CORS policy |
跨域预检未通过、响应头缺 Access-Control-Allow-Origin |
Console + Network 里的预检请求 |
| 4 |
接口返回 404 / 500 |
路径写错、资源被删、服务端异常 |
Network:URL、状态码、响应体摘要 |
| 5 |
Hydration failed because the initial UI does not match |
服务端与客户端首屏渲染结果不一致 |
Console + 出问题的组件位置 |
| 6 |
Unhandled promise rejection |
异步失败没有 catch,错误被吞掉 |
Console + 触发它的动作 |
| 7 |
Refused to load ... violates Content Security Policy |
CSP 未放行新域名或内联脚本 |
Console + 页面的 CSP 响应头 |
| 8 |
Mixed Content: ... loaded over HTTPS, but requested an insecure resource |
页面是 HTTPS,却请求了 HTTP 资源 |
Console + Network 里那条被拦的请求 |
这张表可以直接当报障清单用:看到红字先归类,再按"该去哪看"补证据。
错误、bug、缺陷不是一回事
- 错误(error)是系统给出的信号,可能只是警告,也可能是噪音;
- bug 是"实现和预期不一致",通常需要一个能复现的路径;
- defect 在多数团队的缺陷管理里与 bug 同义,区别只在正式程度。
这组词的分界见Bug 与 Defect 的区别。对报障的人来说,记住一句话就够:错误是线索,bug 是结论。 报告要提供线索,不要替开发下结论。
每类错误该带什么证据
| 错误类型 |
报告里必须有 |
有更好,但没有也能修 |
| 语法 / 运行时 |
报错原文(一字不改)、页面地址、触发动作 |
截图、复现录屏 |
| 引用 / 取值 |
报错原文、出问题的页面路由、登录角色 |
相关接口的返回结构 |
| 网络 / 接口 |
请求 URL、状态码、发起动作、时间点 |
响应体片段(注意脱敏) |
| 逻辑 |
操作步骤、期望结果、实际结果、数据样例 |
录屏 |
| 环境 / 配置 |
浏览器与系统版本、视口、环境标识(生产/预发/预览) |
账号权限、构建号 |
最后一行最容易被忽略:"只有我的电脑上这样"本身就是最重要的信息,它把排查范围从"全站"缩到"某类环境"。
怎么让这些信息不用问就进报告
手动路径是打开开发者工具的 Console 与 Network 面板逐项截图(操作见怎么打开浏览器控制台),但这条路径有三个现实问题:非技术同事不会开、截不全、截完还要人肉对齐时间。
更省事的做法是让提交工具自动带:BugCapturer 的报告默认附带页面地址(敏感参数自动打码)、浏览器与系统、屏幕与视口、时间戳、控制台报错原文、失败请求(4xx/5xx)与状态码。测试同学只需要圈出问题位置、写一句看到的现象,剩下五列证据是自动的。
差别在提交率上:要求报障人先学会看控制台,等于把大部分非技术同事挡在门外;在页面上直接标注再提交,他们才愿意提第二次。
团队要不要给错误建"分类字段"
如果台账里已经有几百条报告,加一个 error_type 字段是有收益的——但只在这三种情况下值得做:
同一类错误反复出现(比如每两周一次 CORS):分类能暴露系统性问题,而不是一条条修;
报障人不是开发:分类能减少"这是前端还是后端"的来回;
要做质量度量:按类型看分布,比按人看更公平。
反过来说,如果团队只有三五个人、每周报告不到二十条,这个字段只会增加填写负担。先保证证据齐全,再谈分类。
三个常见误区
- 把所有红字都当 bug:浏览器扩展、第三方统计脚本、广告拦截器都会往控制台写错误。判断标准是"它是否影响当前页面的行为"。
- 忽略 warning:React 的 key 警告、hydration 警告、弃用警告本身不是 bug,但它们是后续报错的前兆。
- 看到 500 就直接转后端:状态码说明服务端失败,但报告里还缺请求 URL、参数名、发起动作。缺了这三样,后端也只能回一句"再复现一次"。
常见问题
语法错误算 bug 吗?
源码里的语法错误通常进不了线上,属于构建阶段拦截。但如果线上真的出现 SyntaxError,那是发布链路的问题(构建产物没校验、CDN 缓存了旧文件),应当按缺陷处理。
控制台的 warning 要不要写进报告?
只写与现象相关的。比如页面空白且伴随 hydration 警告,就带上;如果只是某个库的弃用提示,别放进去,它会把真正的线索埋掉。
"接口 500"应该报给前端还是后端?
报给谁取决于你们的流程,但报告内容是一样的:请求 URL、状态码、发起动作、时间点、能否稳定复现。先确认是前端传错了参数,还是服务端真的异常。
为什么开发总说"我本地复现不了"?
因为缺的是环境而不是步骤:账号权限、数据量、浏览器版本、时区、feature flag 都可能不同。报告里带上环境字段,这一轮来回就能省掉。
非技术同事怎么提有用的错误信息?
不要让他学开发者工具。装一个浏览器扩展,或者用站点内嵌的反馈入口,把控制台与失败请求交给工具采集——这是即时反馈系统能成立的前提。