一个商品详情页,平时好好的,偶尔有用户反馈白屏。复现不了,直到在监控里翻到一条报错:

TypeError: Cannot read properties of undefined (reading 'name')

代码是这样的:

const detail = await fetchDetail(id);
renderTitle(detail.product.name);

接口偶尔会返回「商品已下架」,此时 product 是 undefined。取 name 直接抛错,后面整段渲染中断,页面停在白屏。更麻烦的是,出问题的用户看到的是空白,而开发这边没有任何兜底提示。

这篇讲什么:错误对象里有什么、throw 和 try/catch 该怎么用、常见报错读法、异步里的错误为什么容易漏、以及线上排查的实际顺序。读完你能做到:看到一条报错先说清楚它在讲什么;给关键路径加上合理的兜底;不再写空的 catch;知道去哪儿看第一条错误。

错误对象:name、message 和 stack

抛出的错误通常是一个 Error 实例,里面最有用的三个属性:

属性内容什么时候用
name错误类型,比如 TypeError、SyntaxError判断是哪一类问题
message具体描述,比如「读取 'name' 失败」日志、给开发看的提示
stack调用栈,出错时一层层的函数和文件行号定位代码位置
try {
  JSON.parse("{bad json");
} catch (err) {
  console.log(err.name);       // SyntaxError
  console.log(err.message);    // 具体内容随浏览器版本不同,通常是解析失败的说明
  console.log(err.stack);      // 多行调用栈
}
各浏览器对 message 的措辞不完全一样,不要用 message 做程序判断,判断用 name 或者自定义错误里的错误码。

stack 不是用来通读的。有用的只有一件事:找第一个属于自己项目的文件名。最上面几行通常是浏览器内部或者框架的调度代码,比如 at async loadDetail;往下翻到 app.js:128 这种,才是你能改的位置。线上代码压缩后是 app.3f2a.js:1:48213,没有 source map 就只剩这一串数字。

Error 对象可以自己挂字段,比如 err.status、err.traceId、err.bizCode,上报时一起带上去。别改 message 和 stack,那是给人和工具看的原始证据。需要包装一层时,把原错误放进 cause,别只留一句「请求失败」:

async function loadDetail(id) {
  try {
    const res = await fetch("/api/detail/" + id);
    if (!res.ok) {
      const err = new Error("详情接口失败");
      err.status = res.status;
      err.traceId = res.headers.get("x-trace-id");
      throw err;
    }
    return await res.json();
  } catch (err) {
    throw new Error("加载详情失败", { cause: err });
  }
}

cause 在较新的浏览器里支持,日志里能看到「外层原因」和「内层原因」两层。如果项目要兼容老环境,至少把原始的 message 和 status 带上,别丢掉。

throw 和 try/catch:别把整段代码都包进去

基本语法很简单:try 里放可能出错的代码,catch 接住,finally 不管成败都执行。真正需要判断的是「包住多少」。包得太大,所有错误都混在一起,分不清是哪里出的;包得太小,又漏掉一些。

async function loadDetail(id) {
  showLoading();

  try {
    const res = await fetch("/api/detail/" + id);
    if (!res.ok) throw new Error("HTTP " + res.status);

    const detail = await res.json();
    return normalize(detail);        // 只包住「取数据并整理」这一段
  } catch (err) {
    console.error("详情加载失败", id, err);
    return null;                     // 明确失败结果
  } finally {
    hideLoading();                   // 成功失败都收尾
  }
}

throw 可以抛任何值,但请抛 Error 实例。抛字符串或数字能跑,但拿到的 err 没有 stack,排查等于瞎猜:

// 不推荐
throw "库存不足";

// 推荐
throw new Error("库存不足");
// 需要区分业务类型时用自定义错误,下面会讲

finally 有个容易忽略的行为:如果 finally 里写了 return,它会覆盖 try 和 catch 的返回值。所以 finally 只用来收尾,别在里面 return。

反过来,包得太小也麻烦。给每一行都套一个 try/catch,看起来稳,实际把「批量导入 1000 行」变成了 1000 个独立的错误处理点,日志里 1000 条一样的报错,真正的原因被淹了:

rows.forEach((row) => {
  try {
    renderRow(row);
  } catch (err) {
    console.error("渲染失败", row.id, err);
  }
});

这种写法不是不能用,前提是你确实要「一行失败不影响其它行」,并且有地方汇总失败数量。如果只是想图安心,它只是把问题从「页面崩了」变成「页面缺了几行还没人知道」。

常见报错怎么读

前端日常见到的报错,来来回回就这几类。能对上号,排查时间能省一大半:

报错实际含义常见原因
Cannot read properties of undefined (reading 'name')你从一个 undefined 上取属性接口少字段、数组越界、异步数据还没到
xxx is not a function名字找到了,但它不是函数导入方式错了、拼写错了、值被覆盖成别的类型
xxx is not defined这个名字在当前作用域里根本不存在变量没声明、拼错、模块没导入
Unexpected token '<'解析时遇到了不该出现的字符接口返回了 HTML 错误页却当 JSON 解析;脚本路径错,服务器返回首页 HTML
Maximum call stack size exceeded调用层数太深,栈满了递归没有终止条件;两个函数互相调用停不下来
Uncaught (in promise)某个 Promise 失败了,但没人 catch忘记 await;then 链没接 catch
xxx.map is not a function值不是数组,却按数组用了接口把列表包了一层,比如 { list: [] } 当成了 []
Script error.跨域脚本的错误被浏览器隐去了细节script 标签有没有 crossorigin,CORS 有没有放行

第一类出现频率最高,处理起来也最直接:在取属性之前确认对象存在。但别到处撒 ?. 把问题盖住,先想清楚「这个字段按约定该不该有」。该有却没有,说明接口或加载逻辑有问题,暴露出来比静默显示空白更好。

第四类特别值得说。本地开发时调接口,控制台报 Unexpected token '<',八成是请求路径写错,服务器把 index.html 返回来了,你拿 HTML 当 JSON 解析。还有一种情况是登录态失效,网关返回一个 HTML 登录页。排查时先看 Network 面板的响应内容,比盯着报错猜快得多。

null 和 undefined 的报错文案不一样,一个是 of null,一个是 of undefined。前者通常是接口明确返回了 null,后者多半是字段根本不存在或变量没赋值。光看这一句就能缩小一半范围。

还有一类报错根本不给细节:Script error.,只有一行,点不开堆栈。这不是代码写错了,是浏览器对跨域脚本的保护。脚本要带 crossorigin 属性加载,服务端也要返回对应的 CORS 头,堆栈才会完整。上线后如果监控里全是这四个字,先查静态资源的部署方式,别去翻业务代码。

异步里的错误,try/catch 不一定接得住

try/catch 只能接住它执行期间同步抛出的错误。异步操作如果没 await,错误发生的时候 try 早就结束了:

// 接不住
try {
  fetch("/api/user").then((r) => r.json());
} catch (err) {
  console.log("这里不会执行");
}

// 接得住:await 把异步结果拉回当前执行流程
try {
  const res = await fetch("/api/user");
} catch (err) {
  console.log("这里能执行");
}

没被接住的 Promise 错误会成为「未处理的拒绝」。开发时控制台有红字,线上如果没做全局监听,就这么静默过去了。可以加一个全局兜底,至少把日志收上去:

window.addEventListener("unhandledrejection", (event) => {
  console.error("未处理的 Promise 错误", event.reason);
  // 上报到日志服务
});

window.addEventListener("error", (event) => {
  console.error("未捕获的错误", event.error);
});

这两个监听是兜底,不是替代。它们只能告诉你「出事了」,不能替你做业务上的降级处理。关键路径还是要自己 try/catch,并决定失败之后页面显示什么。

setTimeout 里的错误同理,外层 try/catch 也接不住,因为回调执行时 try 早就结束了:

// 接不住
try {
  setTimeout(() => {
    throw new Error("定时器里出错");
  }, 0);
} catch (err) {
  console.log("这里不会执行");
}

// 接得住:把 try/catch 放进回调里
setTimeout(() => {
  try {
    doSomething();
  } catch (err) {
    console.error("定时器里出错", err);
  }
}, 0);

事件监听里的错误也是同一类。回调由浏览器调用,你包在外层的 try/catch 管不到它。所以提交表单、删除数据这类关键回调,要在函数内部自己兜住。

程序错误和业务错误,别混为一谈

接口返回 { code: 4001, message: "库存不足" },这不是程序错误,是业务结果。不该用 throw 一路抛到全局,而是就地处理:提示用户、禁用按钮、给出可选操作。

我一般这样分层:

请求层:只负责发请求、解析响应,网络失败和 HTTP 状态异常抛错。
业务层:判断业务错误码,决定是提示、重试还是降级;需要向上传递时抛自定义错误。
页面层:try/catch 包住关键流程,失败时显示可理解的文案,而不是白屏。

自定义错误能让上层区分「哪种失败」:

class ApiError extends Error {
  constructor(message, code) {
    super(message);
    this.name = "ApiError";
    this.code = code;
  }
}

try {
  await saveOrder(order);
} catch (err) {
  if (err instanceof ApiError && err.code === 4001) {
    toast("库存不足,请调整数量");
  } else {
    toast("保存失败,请稍后重试");
    report(err);
  }
}

注意 instanceof 判断依赖原型链,跨 iframe 或打包多份时可能失效。单页应用里通常没问题,遇到判断失灵再改用 err.name 或错误码。

线上排查,按这个顺序走

排查不是「把代码从头读一遍」,而是从证据往回收缩。我的顺序大概是:

第一步,先看第一条错误。控制台里一串红字,后面的很多是连锁反应。第一条通常才是根因,先把它读明白。
第二步,看堆栈里属于自己的那一层。最顶上往往是浏览器或库的代码,往下翻到你的文件名和行号,那才是能改的地方。
第三步,看 Network。接口报错时,先确认状态码、响应体、请求参数。很多「前端 bug」到这儿就发现是接口返回不对或者参数传错。
第四步,确认能不能稳定复现。稳定复现就二分定位:注释一半逻辑、加日志、缩小范围。偶发问题先看监控里的用户环境、时间、操作路径,找共性。
第五步,线上代码要看 source map。压缩后的行号对不上源码,先确认构建产物有没有上传 source map,再谈定位。

还有一条经验:加日志时带上「能定位这次请求」的信息,比如订单 ID、接口路径、入参。只打印「出错了」的日志,等于没打。日志也不要用 console.log(obj) 打整个对象,控制台里展开看到的是引用当前值,刷新后就变了,用 JSON.stringify 或者结构化字段。

偶发问题还要多走一步:把「用户、版本、时间」对齐。同一条错误如果集中在某个版本号,基本就是那次发布引入的;集中在某个时间段,先看当时的接口成功率;集中在某一批用户,查他们的数据和权限。我们遇到过一次 1% 的 Cannot read properties of null,最后发现是灰度用户拿到了新接口,字段名从 items 改成了 list,老代码还在读旧字段。三千日活、1% 就是每天三十次,不算少。

完整场景走查:一次 1200 行的价格导入

运营要给 1200 个 SKU 调价,表格六列:SKU、供应商、含税价、税率、生效日期、备注,文件 3.4MB。第一版很直接:读文件、拼数组、一次性提交,整段包一个 try/catch。

async function importPrices(file) {
  try {
    const rows = await parseXlsx(file);            // 1200 行
    await postJSON("/api/prices/import", { rows });
    toast("导入成功");
    reloadTable();
  } catch (err) {
    toast("导入失败,请检查文件");
    console.error(err);
  }
}

本地拿 20 行样例测,一次通过。上线当天运营传了全量文件,页面转了 30 秒,网关 504,提示「导入失败」。运营改了个错别字重传,价格表里出现了两批重复数据:后端其实已经写进去 800 行,只是响应超时没回来。

三个问题,按严重程度排:整批提交没有超时预算;失败只给一句「导入失败」,不知道哪一行错;重试不幂等,同一批数据能写两遍。

先做本地校验,把能提前发现的错挡在提交之前,并且带行号。第 1 行是表头,数据从第 2 行算:

function validateRow(row, line) {
  const errors = [];
  const price = Number(row.price);
  const rate = Number(row.taxRate);

  if (!row.sku) errors.push("SKU 为空");
  else if (!/^[A-Z0-9-]{6,20}$/.test(row.sku)) errors.push("SKU 格式不对");

  if (!Number.isFinite(price) || price <= 0) {
    errors.push("含税价必须是大于 0 的数字");
  } else if (price > 50000) {
    errors.push("含税价超过 5 万,请确认单位是元");
  }

  if (![0, 0.06, 0.09, 0.13].includes(rate)) {
    errors.push("税率只支持 0、0.06、0.09、0.13");
  }

  return errors.map((msg) => ({ line, sku: row.sku, msg }));
}

价格上限那条不是随手加的。之前有人把「元」当「分」填,12 元的商品录成 1200,第二天结算对不上。校验规则要从业务来,别自己拍。

然后分批提交:1200 行按 50 行一批,共 24 批,单批 200ms 左右,整轮 5 秒上下,单批超时设 10 秒。每批带固定的 requestId,服务端按它做幂等,重复提交直接返回上次结果:

async function importBatches(rows, batchId) {
  const failed = [];
  const size = 50;

  for (let i = 0; i < rows.length; i += size) {
    const batch = rows.slice(i, i + size);

    try {
      const res = await postJSON("/api/prices/import", {
        rows: batch,
        requestId: batchId + "-" + i       // 同一批重试时保持不变
      });
      if (!res.accepted) {
        failed.push({ from: i + 2, reason: res.message });
      }
    } catch (err) {
      if (err.name === "AbortError") {
        failed.push({ from: i + 2, reason: "超时,未确认是否写入" });
        break;                              // 状态不明,后面不再发
      }
      failed.push({ from: i + 2, reason: err.message });
    }
  }

  return failed;
}

超时单独处理的原因:超时的时候你不知道服务端写没写。继续发下一批,可能变成「前面缺一段、后面成功」的错位数据。正确做法是停下来,让运营用同一个 requestId 重试整轮,靠幂等去重。

最后是结果页:成功 1173 行、失败 27 行,失败列表带行号、SKU、原因,可导出。这个页面比任何技术优化都管用。同样 27 条错误,一句「导入失败」换来三通电话,一张带行号的表能让运营自己改完重传。

改完之后整轮 5 到 6 秒,失败可重试且不产生重复;上线三个月遇到两次个别行格式错误,都是运营按行号改掉重传的。回头看,第一版不是逻辑写错,是它把「一次导入」当成了不可分割的操作。批量操作要按「可恢复的最小单元」切分,再给每个单元明确的失败语义。

错误现象对照

排查时先认现象,再验证原因。下面这张表按「你看到什么」反查:

现象真实原因第一步查什么
控制台一条 Uncaught (in promise) Error: HTTP 500,页面没有任何提示 请求层抛了错,调用处没 await 也没接 catch 看堆栈里第一个自己的文件,找到那次请求的调用点,确认有没有 await
整页白屏,Console 干干净净,一条红字都没有 错误被空的 catch 吞了;或者服务端返回了空白 HTML,脚本根本没跑起来 先看 Network 里文档请求的响应体长度,再去搜代码里的空 catch
只有一行 Script error.,点不开堆栈 跨域脚本的报错被浏览器隐去细节,没有 CORS 授权 看 script 标签有没有 crossorigin,响应头有没有 Access-Control-Allow-Origin
报错位置是 app.3f2a.js:1:48213,对不上任何源码 生产构建没上传 source map,或者没开映射 Sources 面板看有没有对应的 .map 文件,构建产物目录里确认一遍
Cannot read properties of null (reading 'length'),偶发 接口某个分支返回 null,代码却默认它一定是数组 Network 里看响应原文,确认 null 是哪个分支返回的
list.map is not a function 拿到的是对象不是数组,分页接口常在外面包一层 打印 Object.keys(res),确认该取 res.list 还是 res
页面卡死后出现 Maximum call stack size exceeded 递归没有终止条件,或者两个函数互相调用 看堆栈里重复出现的函数名,从重复的那一对往下查

表格里最省时间的是第二行:没有报错的白屏往往不是「没出错」,而是错误被接住之后没人管。先确认页面到底有没有渲染出内容,再决定是查接口还是查代码。

边界与代价:兜底兜到什么程度

try/catch 不是越多越好,也不是越少越好。几条能落地的判断:

  • 能提前判断的,别用异常。参数为空、数组长度为 0、状态不合法,用 if 早返回,比抛错再 catch 清楚,也省掉构造 Error 采集堆栈的开销。
  • 能恢复的才 catch。网络失败可以重试、可以降级;在 undefined 上取属性基本是逻辑 bug,catch 住只是把它藏起来,应该让它暴露,或者在上游修掉。
  • 粒度以「一个完整业务动作」为准。加载详情、提交订单各一个 try/catch,别把整个页面生命周期包进去。

?. 也有边界。它只护住左边的值,a?.b.length 在 a 存在、b 为 null 时照样报错。更重要的是区分「可选字段」和「必填字段」:必填字段缺失是接口违约,应该报错、应该报警,不该用 ?. 静默变成 undefined,再让下游把空数据渲染成「暂无」。

全局监听的代价是噪音。unhandledrejection 会被每一个没接住的 rejection 触发,第三方 SDK 一天能贡献几千条。上报前按 message 加堆栈首帧做指纹,5 分钟窗口内只报一次,整体采样 10%;单条内容控制在 4KB 以内,堆栈只留前 5 层,超了日志服务会截断。手机号、地址、token 要脱敏,别为了排查把用户信息整包传上去。

还有两个容易漏的点:资源加载错误(图片、脚本 404)不会冒泡到 window,要用捕获阶段监听 window.addEventListener("error", handler, true);instanceof 判断自定义错误,在 iframe 或多份打包副本里会失效,跨边界传错误时改用 code 或 name。

小结

抛错抛 Error 实例,别抛字符串;try/catch 包住关键流程而不是整页代码,finally 只做收尾。
常见报错先对号:取属性失败多半是数据缺失,not a function 多半是导入或类型问题,Unexpected token '<' 多半是返回了 HTML。
异步错误要 await 才接得住;unhandledrejection 和 error 监听是兜底,不是业务处理。
业务失败给用户可理解的提示和下一步操作;程序错误记日志、上报、降级,别让页面白屏。

今天就能自己验的几件事:

  1. 在控制台跑一次 JSON.parse("{bad"),把 err.name、err.message、err.stack 分别打印出来,认一遍。
  2. 写一个不带 await 的失败请求,看 unhandledrejection 是否触发;再加上 await 和 catch,看它是否被接住。
  3. 给页面加全局监听,人为抛一次错,确认上报内容里有版本号、页面路径和一个能定位请求的 ID。
  4. 打开线上页面,随便制造一个报错,确认能在 Sources 里点回源码行;点不回去就说明 source map 没生效。
  5. 把某个 catch 里的 return [] 改成返回带失败标记的对象,确认页面能区分「空」和「失败」。

下一篇讲事件模型,建议按顺序读。理由不是章节编排,而是这两件事在真实页面里常常连在一起:接口失败之后,用户会去点「重试」按钮,而那个按钮可能根本没绑上,或者绑了三遍。错误处理解决「出事之后怎么办」,事件模型解决「用户操作怎么被接住」;一个没绑好的事件比抛错更难查,因为它根本不报错。