TapCub 正式上线:统计、分析、客服一个平台免费用
术语表

什么是 JavaScript 错误?类型、影响和排查优先级

JavaScript 错误是浏览器没能运行脚本的某一部分。报表里有哪些类型、监控会漏掉什么,以及怎样分清会让访客做不了事的错误和只是吵的错误。

陈屿 审核人 伊森·布鲁克斯 又称 JS 报错 最后更新 2026 年 11 月 17 日 术语表

一句话回答

JavaScript 错误,是浏览器没法按写好的样子解析或运行脚本,出错的代码就停了,它负责的功能可能失效,访客通常看不到任何提示。重要的是哪些错误挡住了任务、影响了多少个会话,而不是它发生了多少次。

公式: 错误率 = JavaScript 错误次数 ÷ 页面浏览量

JavaScript 错误是什么

JavaScript 错误,是指浏览器没法按写好的样子解析或运行某段脚本。引擎会生成一个错误对象,出错的那一行就停了,这段代码本来要做的事(打开菜单、校验表单、提交订单)可能就没发生。访客通常什么都看不到:没有提示,只是按钮点了没反应。

所以它和大家平时监控的错误不是一类。HTTP 500 错误是服务器没能响应,软 404 是页面其实不存在却返回了成功状态码。JavaScript 错误可以出在一个加载完全正常的页面上:状态码 200,响应也很快,所以只盯服务端的监控永远看不到它。这个数只有在访客的浏览器上报时才存在。

JavaScript 错误的类型

MDN 列出了语言内置的错误类型。实际在监控报表里,大部分是下面这六种情形:

是什么什么时候抛出访客会注意到什么示例信息
SyntaxError脚本无法解析整个文件都不运行,它负责的功能全部失效Unexpected token '<'
TypeError某个值不是代码预期的类型单个功能失效,常见于按钮或表单Cannot read properties of null (reading 'value')
ReferenceError代码用了不存在的名字单个功能失效;第三方标签没加载成功时很常见gtmFoo is not defined
RangeError数值超出允许范围少见;多半是失控的循环或停不下来的递归Maximum call stack size exceeded
未处理的 Promise 拒绝Promise 失败了,没有任何代码处理失败某个请求悄悄地一直没完成Uncaught (in promise)
跨域的「Script error.」别的域名的脚本抛错,浏览器把细节藏了起来不知道:看不出是哪一行、哪个功能Script error.

还有两样东西常和错误放在一起报告,但并不一样:资源加载失败(图片或脚本文件返回 404 或被拦截)和控制台警告。它们本身都不会让别的代码停下来。

哪些错误会进入监控报表

发生过的错误并不都会被统计,不同工具统计的范围也不一样:

  • 你自己捕获的错误不会出现。 用 try/catch 把错误吞掉的代码,在任何报表里都显得健康,哪怕功能其实坏了。
  • 同步错误和 Promise 拒绝是两种事件。 按 MDN 的说法,窗口的 error 事件只对同步抛出的脚本错误触发;没有处理函数的 Promise 拒绝触发的是 unhandledrejection。只监听其中一种的工具,数字在结构上就会偏低,所以两个工具很少一致。
  • 跨域脚本的细节会被隐藏。 对别的域名下的脚本,HTML 标准为了避免泄露隐私信息而隐藏错误细节,浏览器只上报 Script error.,没有文件、行号和列号。修复要由脚本的所有者来做:脚本响应带上 Access-Control-Allow-Origin 头,页面用 crossorigin="anonymous" 加载,Sentry 的排错指南就是这样写的。
  • 列表为空不等于站点健康。 如果采集从没开过,或者代码片段是旧的,数字为 0 只是因为没人在监听。

会让用户做不了事的错误,和只是吵的错误

一个站点一周产生几千条错误很容易,其中多数并不造成损失。有用的分法是看错误挡住了什么,而不是它叫什么名字:

  • 会让用户做不了事:挡住了访客来做的事(付款、注册、发消息、加载主要内容)。最先修。
  • 降低体验:坏了次要的东西(轮播、提示气泡、某个统计标签)。方便时再修。
  • 噪音:来自你控制不了的代码、你不支持的很旧的浏览器,或者同一个失败被循环重复了很多次。可以过滤或忽略,但要记下原因。

三个问题可以把一个错误放进上面某一类:

  1. 它影响多少个会话? 数会话或访客,不要数发生次数。一个浏览器卡在重试循环里,就能由一个人产生几百条错误。
  2. 它出在哪个页面? 同一个错误出在 /checkout 和出在一篇旧博客上,代价完全不同。
  3. 它是不是发版之后才出现的? 趋势线上和发布时间对得上的台阶,指向引入问题的那次改动。

然后打开一个受影响的会话,看访客接下来做了什么。如果他们离开了,或者反复重试同一个动作,这个错误就是会让用户做不了事的那种。

算例:一周内的五组错误

示例数据:一周 150,000 次页面浏览、45,000 个会话。错误报表里有五组错误。

分组错误页面发生次数会话数占该页会话的比例
ATypeError: Cannot read properties of null (reading 'value')/checkout908585 ÷ 1,200 = 7.1%
B聊天脚本加载失败,并被反复重试所有页面2,4004040 ÷ 45,000 = 0.09%
C来自第三方标签的 Script error.所有页面600520520 ÷ 45,000 = 1.16%
DReferenceError: gtmFoo is not defined/pricing150140140 ÷ 2,100 = 6.7%
E旧浏览器上的 SyntaxError博客706666 ÷ 45,000 = 0.15%

发生次数合计 90 + 2,400 + 600 + 150 + 70 = 3,310,所以错误率是 3,310 ÷ 150,000 = 2.2%(每次页面浏览的错误数)。

按发生次数排序是 B、C、D、A、E,按会话数排序是 C、D、A、E、B。B 组次数最多、影响面最小:2,400 ÷ 40 = 每个会话 60 次,是少数几个浏览器里的重试循环。两种排法都没把真正的问题放在第一位,所以要看结果。A 错误的 85 个会话里,9 个完成了购买(10.6%);其余 1,115 个结账会话转化了 280 次(25.1%)。再看 D 错误:140 个定价页会话里 11 个注册(7.9%),其余 1,960 个里有 156 个(8.0%),所以 D 目前没有造成可测量的损失。

处理顺序:先 A(它挡住了付款),然后 C(查清是谁的脚本,请对方加 CORS 响应头,因为看不见的东西你修不了),再把 D 当作清理。B 需要给重试加上停止条件,E 可以直接忽略。

常见误区

  • 按发生次数排序。 排在最前面的往往是某个浏览器里的一个循环。先按会话数排,再看页面。
  • 把 0 当成健康。 读空报表之前,先确认采集是开着的。
  • 忽略 Script error. 你这一侧调试不了它,却可能涉及几百个会话。去找脚本的所有者,或者把这个标签拿掉。
  • 拿一个工具的错误率和另一个工具比。 监听的事件不同、分母不同(页面浏览、会话、请求),数字就不同。先让错误率的定义对齐,数值才可比。
  • 追着旧浏览器的错误跑。 出在占会话不到 1% 的浏览器版本上的错误,可能是一个取舍决定,而不是缺陷。
  • 没复查就关掉分组。 发布了修复,只有接下来一周这一组一直安静,才算修好。
  • 把页面慢当成错误。 加载时间是另一项测量;页面可以很慢却没有错误,也可以速度完美却已经坏了。

真实访客遇到的错误,要等有人遇到才会出现在报表里。想赶在访客之前发现的问题,从外部定时跑脚本的检查,例如合成监测,是错误报表的补充,不是替代。

在 TapCub 里看 JavaScript 错误

把上面的例子放到 TapCub 里走一遍。完整步骤见怎么查 JavaScript 错误。

  1. 确认采集是开着的。 在 网站统计 › 配置 › SDK 代码 里,确认 JavaScript 错误 已打开,且代码片段含 data-errors="true"。关着的时候,监测 › 错误 页顶会有提示。
  2. 读卡片。 监测 › 错误 有错误次数、错误率(错误次数 ÷ 页面浏览量)、受影响访客和受影响会话。趋势按时间画错误次数,所以发版之后的台阶一眼就能看到。
  3. 分组按会话数排序。 每组有次数、涉及会话和最近出现时间。展开一组,能看到每次发生的时间、页面、地区、设备和会话。B 错误(每会话 60 次)和 A 错误就是在这里分开的。
  4. 打开一个会话。 打开会话 能看到访客在错误之前和之后做了什么,这就回答了它是不是会让用户做不了事。
  5. 把事情收尾。 把处理完的一组标成 已解决 或 已忽略,它就不再出现在 活跃 里。分组下方的「挫败点击」表,列出了点击后 1 秒内出现脚本错误(错误点击)、或同一元素 500 毫秒内被点了至少 3 次(怒点)的页面;页面至少要有 20 次浏览才会列入。

TapCub 的错误页没有上一周期对比,要比较不同的周,需要自己改日期范围。TapCub 只报告错误,不会修复,也不会替你判断哪个会让用户做不了事;这个判断就是第 4 步的会话检查。这个页面只有真实访问,所以没人打开过的页面上的错误不会出现。

资料来源

这个解释清楚吗?

我们会根据反馈修改和补充这篇内容。

陈屿

技术工程师

专注统计代码、SDK 与接口集成文档,从接入验证到问题排查,帮助开发者更顺畅地完成实施。

常见问题

常见追问

大家看完定义后最常问的几个问题。

还有其他问题?

直接和 TapCub 团队聊聊——工作日通常几小时内回复。

用简单的话说,JavaScript 错误是什么?

它是访客浏览器里运行的代码出了故障。浏览器会停下那一段代码,它本来要做的事,比如提交表单或打开菜单,可能就没发生。页面仍然正常加载,所以访客往往什么都看不到。

JavaScript 错误和 HTTP 错误有什么不同?

HTTP 错误(比如 500)是服务器没能响应。JavaScript 错误发生在页面加载之后的浏览器里,所以服务端日志里是一次正常响应。只有访客的浏览器上报了,它才能被统计到。

哪些 JavaScript 错误应该先修?

先修那些挡住访客来做的事、出在重要页面上、并且影响很多会话的错误。按受影响会话数排序,而不是按发生次数,然后打开一个会话看访客接下来做了什么。第三方代码或旧浏览器上的错误通常可以往后放。

为什么只看到「Script error.」,没有任何细节?

脚本来自另一个域名,浏览器把它的错误细节藏了起来。要看到细节,脚本所有者要返回 Access-Control-Allow-Origin 头,页面也要用 crossorigin="anonymous" 加载。否则这个错误很难处理。

在你自己的网站上看这个数字

加一行脚本就能开始,网站和 App 都能接,几分钟内就能看到第一批报表。

看清数据,找到增长。

每一次点击,都有数据依据。装好一行代码,1 分钟看到第一批数据。

无需信用卡 · 统计与客服都有免费版 · 统计无 Cookie