编程错误的类型:6 大类错误与 8 个常见前端报错

编程错误大致分六类:语法错误、运行时错误、引用与取值错误、网络与接口错误、逻辑错误、环境与配置错误。 分类的价值不在背名词,而在于每类错误留下的证据不一样——知道它属于哪一类,才知道报 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 都可能不同。报告里带上环境字段,这一轮来回就能省掉。 非技术同事怎么提有用的错误信息? 不要让他学开发者工具。装一个浏览器扩展,或者用站点内嵌的反馈入口,把控制台与失败请求交给工具采集——这是即时反馈系统能成立的前提。