如何处理 Node.js 应用中的错误：从入门到实践

目录#

错误类型：知己知彼
同步错误处理：坚实的基础
异步错误处理：核心与难点
全局错误处理：最后的防线
- 进程级别：uncaughtException 和 unhandledRejection
- Express.js 应用中的错误处理中间件
最佳实践与模式
总结
参考资料

错误类型：知己知彼#

在深入处理之前，我们首先要了解 Node.js 中常见的错误类型：

操作错误 (Operational Errors)：表示运行时遇到的问题，这些问题通常是可预测的，不应导致应用完全崩溃。例如：
- 网络请求失败（ECONNREFUSED）
- 文件未找到（ENOENT）
- 无效的用户输入
- 数据库连接超时
- 内存不足（OOM）
程序员错误 (Programmer Errors)：代码中的 Bug，通常是不可预测的，应该通过修复代码来解决。例如：
- 未定义的变量（ReferenceError）
- 语法错误（SyntaxError）
- 错误的函数参数（TypeError）
- 未正确处理的异步流程

核心原则：我们的错误处理策略应侧重于优雅地处理操作错误，并让程序员错误在开发阶段尽早暴露和修复。对于无法恢复的程序员错误，有时让进程崩溃并使用进程管理器（如 PM2）重启是更安全的选择。

同步错误处理：坚实的基础#

同步代码的错误处理非常简单直接，使用标准的 try...catch 语句即可。

function readFileSync(path) {
  try {
    const data = fs.readFileSync(path, 'utf8');
    console.log(data);
    return data;
  } catch (error) {
    // 捕获同步操作抛出的错误，如 ENOENT
    console.error('读取文件时发生错误:', error.message);
    // 可以选择将错误向上抛出，或者进行其他处理（如返回默认值）
    // throw error;
    return null;
  }
}

关键点： try...catch 只能捕获同步代码块内的错误。对于异步操作，它无能为力。

异步错误处理：核心与难点#

这是 Node.js 错误处理的核心，其方式取决于你使用的异步模式。

回调函数中的错误#

这是 Node.js 早期的标准模式，遵循“错误优先回调（Error-First Callback）”约定：回调函数的第一个参数永远是错误对象（err），成功时为 null 或 undefined。

const fs = require('fs');
 
fs.readFile('/path/to/file.txt', 'utf8', (err, data) => {
  // 必须首先检查 err
  if (err) {
    console.error('异步读取文件失败:', err);
    return; // 早期返回，避免执行成功逻辑
  }
 
  // 如果没有错误，再处理数据
  console.log('文件内容:', data);
});

最佳实践：永远要在回调函数中检查 err 参数。忽略错误是导致应用行为异常最常见的原因之一。

Promise 的错误处理#

Promise 使用 .then() 和 .catch() 方法来处理成功和失败的状态。

const fs = require('fs').promises; // 使用返回 Promise 的 fs 版本
 
fs.readFile('/path/to/file.txt', 'utf8')
  .then((data) => {
    console.log('文件内容:', data);
  })
  .catch((error) => {
    // .catch 会捕获链中任何 .then 里抛出的错误以及初始 Promise 的拒绝
    console.error('读取文件失败:', error);
  });
 
// 也可以在 .then 中传入第二个函数来处理错误（但不推荐，容易造成链断裂）

链式调用中的错误处理： Promise 的一个强大之处是错误冒泡。链中的任何一个 .then 处理程序抛出的错误（或返回一个被拒绝的 Promise），都会被后续的 .catch 捕获。

doSomething()
  .then(result => doSomethingElse(result))
  .then(newResult => doThirdThing(newResult))
  .then(finalResult => console.log(`最终结果: ${finalResult}`))
  .catch(error => {
    // 上面任何一个环节出错，都会跳到这里
    console.error('操作链中某处出错:', error);
  });

Async/Await 的错误处理#

async/await 是语法糖，它让你能用同步代码的风格编写异步代码。错误处理也回归到熟悉的 try...catch。

async function readFileAsync() {
  try {
    const data = await fs.readFile('/path/to/file.txt', 'utf8');
    console.log('文件内容:', data);
    return data;
  } catch (error) {
    // 捕获 await 表达式抛出的错误
    console.error('使用 Async/Await 读取文件失败:', error);
    // 注意：在 async 函数中抛出错误，相当于返回一个被拒绝的 Promise
    throw error;
  }
}
 
// 调用 async 函数返回一个 Promise，所以也可以用 .catch
readFileAsync().catch(err => console.error('外部捕获:', err));

最佳实践：对于复杂的异步逻辑，async/await 配合 try...catch 通常能产生更清晰、更易维护的代码。

全局错误处理：最后的防线#

即使代码中有了局部的错误处理，也总会有未被捕获的异常。这些“漏网之鱼”需要全局处理器来兜底，防止整个进程突然崩溃（尽管有时崩溃是必要的）。

进程级别：`uncaughtException` 和 `unhandledRejection**#

uncaughtException：捕获整个进程中未被任何 try...catch 处理的同步错误。
unhandledRejection：捕获未被处理的被拒绝的 Promise（即没有 .catch 的 Promise）。

// 捕获未被捕获的同步异常
process.on('uncaughtException', (error) => {
  console.error('有一个未捕获的异常！', error);
  // 记录错误、清理资源（如关闭数据库连接）
  // 注意：在此事件后，应用处于未知状态，继续运行可能很危险。通常建议记录错误后优雅退出。
  process.exit(1);
});
 
// 捕获未被处理的 Promise 拒绝
process.on('unhandledRejection', (reason, promise) => {
  console.error('有一个未处理的 Promise 拒绝！', reason);
  // 同样，记录错误并考虑退出
  process.exit(1);
});

重要警告：这些事件是最后的手段。一旦触发，说明你的应用处于一个不可恢复的不稳定状态。正确的做法是记录详细的错误信息，执行必要的清理（如关闭数据库连接），然后立即退出进程。使用像 PM2 这样的进程管理器可以自动重启崩溃的应用。

Express.js 应用中的错误处理中间件#

在 Express 框架中，错误处理中间件是处理错误的推荐方式。它通过定义一个有四个参数 (err, req, res, next) 的中间件函数来实现。

const express = require('express');
const app = express();
 
// ... 你的路由和其他中间件 ...
 
// 错误处理中间件（必须放在所有路由和其他中间件之后）
app.use((err, req, res, next) => {
  // 记录错误到日志系统
  console.error(err.stack);
 
  // 根据错误类型设置 HTTP 状态码
  const statusCode = err.statusCode || 500;
 
  // 向客户端返回错误信息
  // 在生产环境中，不要返回详细的堆栈跟踪信息，以免暴露系统细节
  res.status(statusCode).json({
    status: 'error',
    message: statusCode === 500 ? '内部服务器错误' : err.message
  });
});
 
app.listen(3000);

如何将错误传递给这个中间件？

同步路由处理器中的错误会自动被 Express 捕获并传递给错误中间件。
异步路由处理器中的错误，必须手动调用 next(error)。

app.get('/user/:id', async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) {
      const error = new Error('用户未找到');
      error.statusCode = 404;
      return next(error); // 传递错误给中间件
    }
    res.json(user);
  } catch (error) {
    // 捕获 await 或 try 块内的错误
    next(error); // 传递错误给中间件
  }
});

最佳实践与模式#

错误传播#

不要在每个函数中都处理错误。有时，更清晰的做法是让错误向上冒泡，让调用链上层的、更合适的上下文来处理它。对于 Promise 和 Async/Await，这通过 throw 或返回被拒绝的 Promise 自然发生；对于回调，则通过将错误传递给回调函数实现。

操作类错误 vs 程序员错误#

操作类错误：应被捕获，并给出有意义的响应（如“服务暂时不可用，请重试”）。
程序员错误：在开发阶段应通过完善的测试和代码审查来避免。在生产环境中，这类错误通常意味着应用状态不可信，记录错误并重启进程可能是最佳选择。

集中式日志记录与监控#

不要仅仅使用 console.error。使用专业的日志库（如 Winston、Pino）将错误记录到文件或日志系统中。同时，集成监控和告警工具（如 Sentry、Datadog），以便在错误发生时能及时通知开发团队。

// 使用 Winston 的示例
const logger = require('./logger'); // 你的日志配置模块
 
process.on('uncaughtException', (error) => {
  logger.error('未捕获的异常，即将退出', error);
  process.exit(1);
});

优雅关闭#

当进程需要退出时（无论是由于错误还是正常关闭），应实现优雅关闭逻辑：停止接收新请求、完成正在进行的请求、关闭数据库连接等。

// 优雅关闭示例
process.on('SIGTERM', () => {
  console.log('收到 SIGTERM 信号，开始优雅关闭');
  server.close(() => {
    console.log('HTTP 服务器已关闭');
    // 关闭数据库连接等
    db.close(() => {
      console.log('数据库连接已关闭');
      process.exit(0);
    });
  });
});

总结#

Node.js 中的错误处理是一个多层次、多策略的复杂话题。一个健壮的应用应该具备：

局部精确处理：在异步操作（回调、Promise、Async/Await）和同步代码中适时使用错误处理机制。
框架级兜底：在 Web 框架（如 Express）中使用错误处理中间件。
进程级防护：通过 uncaughtException 和 unhandledRejection 事件防止进程静默崩溃，并实现优雅关闭。
运维级支持：结合集中式日志记录、监控和进程管理工具，形成完整的可观测性和恢复体系。

掌握这些技巧将极大提升你开发的 Node.js 应用的稳定性和可靠性。

目录#