一个商品详情页,平时好好的,偶尔有用户反馈白屏。复现不了,直到在监控里翻到一条报错:
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 一路抛到全局,而是就地处理:提示用户、禁用按钮、给出可选操作。
我一般这样分层:
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 或错误码。
线上排查,按这个顺序走
排查不是「把代码从头读一遍」,而是从证据往回收缩。我的顺序大概是:
还有一条经验:加日志时带上「能定位这次请求」的信息,比如订单 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 监听是兜底,不是业务处理。今天就能自己验的几件事:
- 在控制台跑一次
JSON.parse("{bad"),把err.name、err.message、err.stack分别打印出来,认一遍。 - 写一个不带
await的失败请求,看unhandledrejection是否触发;再加上await和catch,看它是否被接住。 - 给页面加全局监听,人为抛一次错,确认上报内容里有版本号、页面路径和一个能定位请求的 ID。
- 打开线上页面,随便制造一个报错,确认能在 Sources 里点回源码行;点不回去就说明 source map 没生效。
- 把某个
catch里的return []改成返回带失败标记的对象,确认页面能区分「空」和「失败」。
下一篇讲事件模型,建议按顺序读。理由不是章节编排,而是这两件事在真实页面里常常连在一起:接口失败之后,用户会去点「重试」按钮,而那个按钮可能根本没绑上,或者绑了三遍。错误处理解决「出事之后怎么办」,事件模型解决「用户操作怎么被接住」;一个没绑好的事件比抛错更难查,因为它根本不报错。