1 / 4概念
Error
失败与边界是同一件事的两面:函数在边界处失败,模块是边界的物理形态。判断标准不是会不会写 try,而是能否说清一个错误从产生到被处理之间,经过了哪些包装,跨过了哪些模块边界。
1 概念
1.1 一句话定义
错误是普通的值,可以抛、可以接、可以包上一层原因。模块是一张静态图,导入在求值之前就被链接,导出是活的只读视图,而不是值的拷贝。
1.2 它解决什么问题
- 失败可诊断:类型化错误加
cause链保留原始现场。 - 失败可恢复:调用方按类型决定重试、降级还是上报。
- 依赖可分析:静态导入让打包器画出依赖图并做裁剪。
- 边界可替换:模块导出与条件导出让同一份代码适配不同运行时。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| Promise 拒绝与未处理拒绝的调度 | Async and Concurrency |
类型标注与 never 的收窄 | TS Type System |
| 测试策略与覆盖率 | Quality & Testing |
| 打包产物与 tree-shaking 实现 | Toolchain |
Node 的 errno 与系统错误码 | Runtime Environment |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 抛出 | throw 一个值 | 可以抛任意值,不只 Error |
| 捕获 | try 加 catch | 捕获后不处理等于吞错 |
| 错误包装 | 新错误携带旧错误 | 用 cause,不要拼字符串 |
cause | 错误的原因链 | 只在构造时传入,之后可改但没人看 |
AggregateError | 多个错误的集合 | 单个错误不要用它 |
| ESM | 静态模块格式 | 导入在求值前链接 |
| 活绑定 | 导入是只读视图 | 不是值的拷贝 |
| 循环依赖 | 两个模块互相导入 | 一侧会拿到未初始化的绑定 |
| CJS | require 的运行时格式 | 缓存按解析后路径 |
| 双包危害 | 同一包被加载两份 | 两份模块状态不共享 |
2 机制
2.1 心智模型
错误沿着调用栈向上走,直到被某个 catch 接住;没有接住就到达顶层。模块沿着导入边向下走,链接发生在求值之前;没有链接成功,一行代码都不会执行。
2.2 机制拆解
- 错误对象:
name、message、stack、cause四个字段;stack是引擎附加的,不是规范强制格式。 - 捕获范围:
try只覆盖同步部分;await之后的异步失败要由 Promise 链或外层try接住。 finally的优先级:finally里的return或throw会覆盖try与catch的结果。- 子类陷阱:编译到 ES5 时
extends Error的原型链会断,instanceof失效;需要手动修prototype。 - ESM 链接:导入声明提升到模块顶部,绑定在链接期建立,求值期只赋值。
- 活绑定:导入方拿到的是指向导出变量的引用,导出方重新赋值,导入方立刻看到新值。
- 循环依赖:ESM 先创建绑定再求值,未初始化的绑定访问会抛
ReferenceError;CJS 返回已执行部分的对象。 - 条件导出:
exports里的条件按书写顺序匹配,第一个命中的生效。
2.3 完整枚举
内建 Error 的八个类型,这是完整集合:
| 类型 | 何时由引擎抛出 | 何时自己用 |
|---|---|---|
Error | 通用错误 | 应用层基类 |
TypeError | 类型不符、调用不可调用之物 | 参数类型错误 |
RangeError | 数值越界、非法长度 | 数值超出定义域 |
SyntaxError | 解析失败 | 解析外部文本失败 |
ReferenceError | 访问未声明绑定 | 配置缺项 |
EvalError | eval 相关 | 几乎不再使用 |
URIError | decodeURI 等失败 | URI 解析失败 |
AggregateError | Promise.any 全部失败 | 批量操作汇总失败 |
try 语句的四种路径与结果:
| 路径 | 发生条件 | 返回值来源 |
|---|---|---|
| 正常结束 | try 块跑完 | try 的最后一个表达式 |
| 捕获后结束 | catch 跑完 | catch 的返回值 |
finally 覆盖 | finally 里有 return | finally 的返回值 |
| 未捕获 | 没有 catch 或 catch 再抛 | 向上传播 |
模块互操作的四种组合:
| 导入方 | 被导入 | 结果 |
|---|---|---|
| ESM | ESM | 活绑定,静态链接 |
| ESM | CJS | 默认导出是 module.exports,具名导出靠静态分析 |
| CJS | CJS | 运行时对象,按路径缓存 |
| CJS | ESM | 新版 Node 支持 require ESM,旧版抛 ERR_REQUIRE_ESM |
循环依赖的两种表现:
| 格式 | 表现 | 典型症状 |
|---|---|---|
| ESM | 绑定存在但未初始化 | 访问时抛 ReferenceError |
| CJS | 返回已执行部分 | 读到 undefined 或缺失方法 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 调用栈深度 | 约一万帧 | 错误栈同样受此限制 |
| 错误信息长度 | 百字节级 | 太长的信息会被日志截断 |
| 条件导出顺序 | 首个匹配生效 | types 必须排在最前 |
| 模块图规模 | 数千到数万 | 影响启动与打包时间 |
throw 成本 | 高于普通返回 | 不要用异常做热路径分支 |
| 栈字符串化 | 毫秒级 | 大量错误会拖慢日志 |
3 实践
3.1 最小示例
一个模块导出解析函数,抛出类型化错误并保留原因;另一个模块导入并区分处理。两个机制各出现一次:错误包装与静态导入。
// modules/parse-user.ts
export class ValidationError extends Error {
constructor(message: string, options?: {cause?: unknown}) {
super(message, options);
this.name = 'ValidationError';
}
}
export function parseUser(raw: string): {id: string; name: string} {
let data: unknown;
try {
data = JSON.parse(raw);
} catch (error) {
throw new ValidationError('user payload is not JSON', {cause: error});
}
if (typeof data !== 'object' || data === null) {
throw new ValidationError('user payload is not an object');
}
const {id, name} = data as {id?: unknown; name?: unknown};
if (typeof id !== 'string' || typeof name !== 'string') {
throw new ValidationError('user payload misses id or name');
}
return {id, name};
}
// app.ts
import {parseUser, ValidationError} from './modules/parse-user';
try {
const user = parseUser('{"id":"u1"}');
console.log(user.id);
} catch (error) {
if (error instanceof ValidationError) {
console.error(error.message, error.cause); // cause 里是原始 SyntaxError
} else {
throw error; // 不是本层能处理的,继续向上
}
}
追踪:JSON.parse 成功,但缺 name,第二个校验抛 ValidationError,cause 为空。若输入是 '{"id":',JSON.parse 抛 SyntaxError,被 catch 接住后包装成 ValidationError,cause 指向原始 SyntaxError。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 抛错 | throw new TypeError(msg) | 不用字符串 |
| 包装 | new Error(msg, {cause}) | 保留原始错误 |
| 可选绑定 | catch {} | 明确忽略时使用 |
| 判断类型 | error instanceof TypeError | 跨 realm 会失效 |
| 判断形状 | typeof error === 'object' && 'code' in error | 跨包错误更稳 |
| 聚合 | new AggregateError(errors, msg) | errors 是数组 |
| 动态导入 | await import('./heavy.js') | 返回命名空间对象 |
| 当前模块元数据 | import.meta.url | ESM 独有 |
| CJS 里用 ESM | createRequire(import.meta.url) | 互操作兜底 |
| 条件导出 | exports 里的 import/require | 顺序敏感 |
3.3 标准流程
- 先在边界定义错误类型,一个模块一组,不要全用
Error。 - 入口处校验外部输入,失败即抛,带上是哪个字段。
- 跨层包装时传
cause,不要拼接字符串。 - 顶层集中处理:分类、记录、映射到状态码或退出码。
- 模块只导出必要符号,内部实现留在模块内。
- 用单测覆盖每条错误路径,断言
name与cause。
3.4 与相邻技术的组合
- 异步:
async函数里的throw等价于返回拒绝的 Promise。 - HTTP 框架:异常过滤器把错误类型映射成状态码,业务层不写
res.status。 - 日志:结构化日志记录
name、message、cause与请求 id。 - TypeScript:
unknown接收catch变量,收窄后才能读字段。 - 打包器:条件导出与
sideEffects决定能否 tree-shake。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 失败表达 | throw / 返回值 / 事件 | 调用方负担与控制流 |
| 错误粒度 | 每模块一组 / 全局一组 | 可诊断性与耦合 |
| 模块格式 | ESM / CJS | 静态分析与互操作 |
| 导出面 | 具名 / 默认 / 两者 | tree-shaking 与兼容 |
| 互操作策略 | 双格式 / 单格式加包装 | 双包危害风险 |
3.6 决策规则
- 预期内的分支用返回值,不可预期的失败用
throw。 - 新代码一律 ESM;需要兼容旧包时通过
exports提供两种条件导出。 - 错误类按领域划分,继承
Error,并设置name。 - 跨层包装必须带
cause;不要重新拼一条丢失现场的信息。 - 顶层必须有未处理拒绝与未捕获异常的兜底记录。
- 循环依赖出现时改结构,不要靠调整导入顺序绕过。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
throw | 调用方不写检查 | 控制流隐式 | 不可预期失败 |
返回 Result | 失败显式 | 每层都要处理 | 可预期失败 |
| 事件上报 | 不打断主流程 | 容易被忽略 | 非关键失败 |
| 单格式 ESM | 无双包危害 | 旧环境要转译 | 新项目 |
| 双格式导出 | 兼容面广 | 两份状态 | 发布给他人用的库 |
3.8 何时不该用
- 不要用异常表达正常分支,例如「没找到」。
- 不要在新代码里用 CJS 与
require。 - 不要用
AggregateError包单个错误。 - 不要在
finally里return,会吞掉异常。 - 不要为每个函数造一个错误类,按领域分组即可。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 错误出现在日志里但没人处理 | catch 里只写 console.log | 分类后重抛或映射 |
| 异常被静默吞掉 | finally 里有 return | 移除 finally 的返回 |
instanceof 判断失败 | 编译到 ES5 或跨 realm | 用 name 或 code 判断 |
循环依赖处拿到 undefined | ESM 绑定未初始化 | 拆模块,或延迟调用 |
import 具名导出为 undefined | CJS 包无法静态分析 | 用默认导入再解构 |
| 同一包有两份状态 | 双包危害 | 单一格式,或 exports 收敛 |
| 进程意外退出 | 未处理的 Promise 拒绝 | 顶层监听并记录 |
| 错误信息里出现数据库语句 | 直接透传原始错误 | 边界处映射成对外信息 |
| 动态导入路径失效 | 变量拼路径,打包器无法分析 | 用静态映射表 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
空 catch | 失败消失 | 至少记录并重抛 |
throw 'failed' | 没有栈与类型 | throw new Error |
| 用异常做控制流 | 性能差、语义乱 | 返回值或判别联合 |
| 拼接错误字符串 | 丢现场 | cause |
| 深层相对路径导入 | 重构即断 | 路径别名或包导出 |
巨型 index.ts 汇总导出 | 依赖图爆炸 | 按子路径导出 |
4.3 可观测信号
未处理拒绝计数、按 name 分组的错误率、cause 链深度、模块图里的循环边、启动时加载的模块数、错误日志中被截断的比例。
4.4 安全 / 性能 / 一致性边界
- 信息泄露:原始错误可能含路径、SQL、内部主机名;对外只暴露错误码与人类可读信息。
- 性能边界:
throw与栈捕获成本高,热路径用返回值;日志采样,避免错误风暴打满磁盘。 - 一致性边界:对外错误码表要版本化,新增错误必须先在表里登记。
- 加载边界:顶层
await会推迟模块求值,启动路径上慎用。