Node.js / 系统课时
处理异步错误
处理异步错误
异步错误最难排查的原因不是“错误会消失”,而是错误会沿不同通道传播:回调用 err,Promise 用 rejection,async 函数把 throw 变成拒绝。本节把三种通道统一到明确的错误边界。
学习目标
- 能判断回调、Promise 和
async/await中错误实际会传到哪里。 - 能用
try/catch、.catch()和 error-first callback 正确接住失败。 - 能在程序入口设置最终错误边界,避免未处理拒绝悄悄扩散。
三种错误通道不要混用
Node.js 传统回调通常采用 error-first 约定:第一个参数是 err,成功时为 null。Promise 中抛出的异常会转成 rejection;async 函数内部 throw 也会让该函数返回的 Promise 进入 rejected 状态。
| 场景 | 错误通道 | 正确接法 |
|---|---|---|
fs.readFile 回调 |
callback(err, data) |
先检查 err 并立即返回 |
| Promise 链 | rejection | 末尾 .catch() 或上层 await |
async 函数 |
返回 rejected Promise | try/catch 包住 await |

用一个入口统一收口错误
下面示例适用于 Node.js 20+,同时演示回调、Promise 和 async/await。三个分支都读取不存在的文件,并最终把错误转换为稳定、可记录的 ENOENT 错误码。
const { readFile } = require('node:fs');
const { readFile: readFilePromise } = require('node:fs/promises');
function loadJsonCallback(file, callback) {
readFile(file, 'utf8', (err, text) => {
if (err) return callback(err);
try {
callback(null, JSON.parse(text));
} catch (error) {
callback(error);
}
});
}
async function loadJson(file) {
const text = await readFilePromise(file, 'utf8');
return JSON.parse(text);
}
function callbackDemo() {
return new Promise((resolve) => {
loadJsonCallback('missing.json', (err) => {
if (err) console.error('callback:', err.code ?? err.name);
resolve();
});
});
}
async function promiseDemo() {
await loadJson('missing.json').catch((error) => {
console.error('promise:', error.code ?? error.name);
});
}
async function asyncDemo() {
try {
await loadJson('missing.json');
} catch (error) {
console.error('async:', error.code ?? error.name);
}
}
async function main() {
await callbackDemo();
await promiseDemo();
await asyncDemo();
}
main().catch((error) => {
console.error('fatal:', error);
process.exitCode = 1;
});预期输出:
callback: ENOENT
promise: ENOENT
async: ENOENTloadJsonCallback 中 JSON.parse 必须在回调内部捕获,因为这个回调是在未来的事件循环阶段执行;包在 readFile(...) 外层的 try/catch 捕获不到之后才发生的异常。Promise 版本则可以让异常自然转成 rejection,再由调用层统一处理。
把 try/catch 放在真正的 await 边界
当一个函数能自行恢复时,就在该层处理,例如读取可选配置失败后使用默认值;如果无法恢复,就不要只打印日志后继续,而应继续 throw,让上层决定重试、返回 HTTP 500 或终止启动。
对多个顺序步骤,推荐只包住需要统一处理的一段 await,并在 finally 释放资源。数据库事务、文件句柄和锁都适合这个结构:成功提交,失败回滚,finally 做无条件清理。这样错误不会因为层层 .catch() 被重复记录三四次。
进程级事件只做最后兜底
process.on('unhandledRejection', ...) 和 process.on('uncaughtException', ...) 可以用于最后日志记录,但不应承担正常业务恢复。前者说明某个 Promise 没有被处理,后者表示异常已经逃出调用栈;此时继续长期运行可能留下不完整状态。
服务入口更可控的做法是让 main() 返回 Promise,并像示例一样使用 main().catch(...) 设置 process.exitCode = 1。这样启动失败会以非零退出码结束,进程管理器才能识别失败并按既定策略重启,而不是把错误吞掉后继续提供不可靠服务。