Node.js 生产级错误处理与优雅降级机制设计
一、Node.js 错误处理的常见误区
服务端错误处理的质量直接决定系统的可靠性。在实际项目中，常见以下误区：
误区一，用 try-catch 包裹所有代码。过度使用 try-catch 会掩盖真正的逻辑错误，让程序在异常状态下继续运行，产生错上加错的结果。
误区二，依赖process.on('uncaughtException')兜底。这个处理器是在进程已经处于不确定状态时触发的。按照 Node.js 官方建议，捕获后应立即执行优雅退出，而不是尝试恢复。
误区三，Promise 链缺少 catch。未处理的 Promise rejection 在 Node.js 15 之后会导致进程退出。这在实际生产中已经引发过多起事故。
误区四，错误日志信息不足。仅记录error.message而忽略error.stack和上下文信息，导致排查困难。
flowchart TB A[请求进入] --> B{同步代码} B -->|异常| C[try-catch 捕获] B -->|正常| D{异步操作} C --> E[记录错误上下文] E --> F[返回标准化错误响应] D -->|reject| G[.catch 捕获] D -->|resolve| H{业务逻辑} G --> E H -->|业务异常| I[自定义错误类] H -->|成功| J[返回成功响应] I --> E二、错误分类与自定义错误体系
生产环境中的错误需要分层分类。不同类别的错误需要不同的处理策略。
// 错误基类 abstract class AppError extends Error { abstract readonly statusCode: number; abstract readonly errorCode: string; abstract readonly isOperational: boolean; constructor(message: string) { super(message); this.name = this.constructor.name; Error.captureStackTrace(this, this.constructor); } } // 客户端错误 (4xx) class BadRequestError extends AppError { readonly statusCode = 400; readonly errorCode = 'BAD_REQUEST'; readonly isOperational = true; } class UnauthorizedError extends AppError { readonly statusCode = 401; readonly errorCode = 'UNAUTHORIZED'; readonly isOperational = true; } class NotFoundError extends AppError { readonly statusCode = 404; readonly errorCode = 'NOT_FOUND'; readonly isOperational = true; } class ValidationError extends AppError { readonly statusCode = 422; readonly errorCode = 'VALIDATION_ERROR'; readonly isOperational = true; readonly details: Record<string, string[]>; constructor(message: string, details: Record<string, string[]> = {}) { super(message); this.details = details; } } // 服务端错误 (5xx) class InternalError extends AppError { readonly statusCode = 500; readonly errorCode = 'INTERNAL_ERROR'; readonly isOperational = false; } // 外部依赖错误 class ExternalServiceError extends AppError { readonly statusCode = 502; readonly errorCode = 'EXTERNAL_SERVICE_ERROR'; readonly isOperational = true; readonly serviceName: string; constructor(serviceName: string, message: string) { super(`${serviceName}: ${message}`); this.serviceName = serviceName; } }frame是关键标志。操作性错误（如参数校验失败、外部服务超时）是预期的异常，可以返回给客户端。程序性错误（如类型错误、空指针）是代码 bug，不应暴露内部细节给客户端。
常见踩坑记录
在实际项目中，自定义错误体系最容易踩以下坑：
坑一，忘记设置Error.captureStackTrace。在 TypeScript/ES6 中，继承Error的子类如果不调用Error.captureStackTrace(this, this.constructor)，堆栈信息会指向错误类本身而不是抛出错误的位置，导致排查时无法定位源码行号。上述代码中已经在基类构造函数里正确处理了这一点。
坑二，instanceof在多模块场景下失效。如果错误类在errors.ts中定义，但在不同子模块中分别import，某些打包工具（如 webpack 的模块隔离）可能导致instanceof检查失败。解决方案是在错误对象上附加一个kind字符串标识，用error.kind === 'AppError'做兜底判断。
坑三，错误序列化时丢失原型链信息。将错误对象通过JSON.stringify上报到日志系统后，再反序列化时instanceof AppError会返回false。需要在上报前将错误的关键字段（statusCode、errorCode、isOperational）显式提取到普通对象中。
在实际项目中使用自定义错误体系
在业务逻辑层中，使用自定义错误类可以让错误处理更加清晰。例如，在用户服务中：
import { NotFoundError, ValidationError, ExternalServiceError } from './errors'; async function getUserProfile(userId: string): Promise<UserProfile> { if (!userId || typeof userId !== 'string') { throw new ValidationError('用户ID格式错误', { userId: ['用户ID必须是非空字符串'], }); } const user = await db.users.findById(userId); if (!user) { throw new NotFoundError(`用户不存在: ${userId}`); } try { const avatarUrl = await storageService.getSignedUrl(user.avatarKey); return { ...user, avatarUrl }; } catch (error) { // 外部服务（对象存储）调用失败，返回降级数据 throw new ExternalServiceError( 'storage-service', `获取用户头像失败: ${error instanceof Error ? error.message : '未知错误'}`, ); } }在控制器层，不需要写 try-catch，错误会沿着调用栈向上传递，最终被统一错误处理中间件捕获。这避免了在每个路由中重复写错误处理代码。
错误日志的结构化输出
在生产环境中，错误日志需要包含足够的上下文信息用于排查。推荐的结构化日志格式：
interface ErrorLogEntry { timestamp: string; level: 'error' | 'fatal'; errorCode: string; message: string; stack?: string; request?: { method: string; url: string; requestId: string; userId?: string; userAgent?: string; }; metadata?: Record<string, unknown>; } function logError(error: Error, req?: Request): void { const entry: ErrorLogEntry = { timestamp: new Date().toISOString(), level: error instanceof AppError && !error.isOperational ? 'fatal' : 'error', errorCode: error instanceof AppError ? error.errorCode : 'UNKNOWN_ERROR', message: error.message, stack: error.stack, }; if (req) { entry.request = { method: req.method, url: req.originalUrl, requestId: req.headers['x-request-id'] as string || 'unknown', userId: (req as any).user?.id, userAgent: req.get('user-agent'), }; } // 程序性错误立即触发告警 if (error instanceof AppError && !error.isOperational) { triggerAlert(entry); } console.error(JSON.stringify(entry)); }这种结构化格式便于日志分析工具（如 ELK、Datadog）进行检索和聚合。可以按errorCode维度统计各类错误的发生频率，快速定位最高频的错误类型。
flowchart LR subgraph 错误类型 A[Operational Error] --> A1[参数校验失败] A --> A2[资源不存在] A --> A3[外部服务超时] A --> A4[认证/授权失败] B[Programmer Error] --> B1[类型错误] B --> B2[空指针] B --> B3[断言失败] end subgraph 处理策略 A1 --> C1[返回 4xx + 错误详情] A2 --> C1 A3 --> C2[返回 502 + 服务名] A4 --> C3[返回 401/403] B1 --> D1[记录完整堆栈] B2 --> D1 B3 --> D1 D1 --> D2[返回 500 + 通用消息] end三、Express/Koa 中间件错误处理
在 Web 框架层，需要一个统一的错误处理中间件来接管所有未被局部捕获的错误。
Express 版本的完整实践
在实际项目中，Express 错误处理中间件需要注意以下几个细节：
第一，中间件必须注册在所有业务路由之后，且参数签名必须是四个（err, req, res, next），少一个参数 Express 就不会将其识别为错误处理中间件。
第二，对于流式响应（如文件下载、SSE），错误信息无法通过 JSON 返回，需要在响应头已发送的情况下做特殊处理：
function errorHandler(err: Error, req: Request, res: Response, _next: NextFunction): void { // 如果响应头已发送（如流式场景），只能记录日志并结束响应 if (res.headersSent) { console.error('[Error] 响应头已发送，无法返回错误 JSON:', { message: err.message, url: req.originalUrl, }); res.end(); return; } // ... 原有处理逻辑 }第三，对于大文件上传场景，需要在multer等中间件之前注册错误处理器，否则文件大小超限的错误会被 Express 默认错误处理器捕获，返回 HTML 格式的错误页。
Koa 版本的核心逻辑类似，但使用中间件的不同模式：
Koa 的错误处理有两种模式：中间件try/catch模式和应用级error事件模式。推荐两者结合使用：
import { Context, Next } from 'koa'; // 模式一：中间件捕获（处理请求级的错误） async function errorMiddleware(ctx: Context, next: Next): Promise<void> { try { await next(); } catch (err) { const error = err as Error; ctx.status = error instanceof AppError ? error.statusCode : 500; ctx.body = { error: { code: error instanceof AppError ? error.errorCode : 'INTERNAL_ERROR', message: error instanceof AppError && error.isOperational ? error.message : '服务器内部错误', requestId: ctx.get('x-request-id') || undefined, }, }; // 触发应用层面的错误事件（用于日志上报） ctx.app.emit('error', error, ctx); } } // 模式二：应用级错误监听（处理未进入中间件的错误，如 JSON 解析失败） app.on('error', (error: Error, ctx: Context) => { const entry = { timestamp: new Date().toISOString(), message: error.message, stack: error.stack, method: ctx.method, url: ctx.url, requestId: ctx.get('x-request-id'), }; console.error(JSON.stringify(entry)); // 程序性错误触发告警 if (error instanceof AppError && !error.isOperational) { triggerAlert(entry); } });踩坑记录：Koa 与 @koa/router 的错误传播
Koa 的中间件链中，如果某个中间件没有await next()，后续中间件不会执行，错误也不会传播到外围的错误处理中间件。常见的坑是在自定义中间件中忘记了await：
// ❌ 错误写法：忘记 await，错误无法被外层捕获 app.use(async (ctx, next) => { next(); // 没有 await }); // ✅ 正确写法 app.use(async (ctx, next) => { await next(); });此外，Koa 的ctx.throw()方法抛出的错误是HttpError类型，不是我们定义的AppError。需要在错误处理中间件中额外判断：
if (error instanceof HttpError) { ctx.status = error.status; ctx.body = { error: { code: `HTTP_${error.status}`, message: error.message } }; return; }四、优雅降级与容错设计
优雅降级的核心理念是"局部失败不影响整体"。
外部服务降级的三种策略
实际项目中的外部服务调用降级，通常需要组合以下三种策略：
策略一：缓存兜底（已展示的fetchWithFallback）。适用于读取型接口，如获取用户信息、配置数据等。关键是合理设置 TTL，避免返回过期数据导致业务逻辑错误。
策略二：默认值降级。适用于非核心功能，如"相关推荐"模块调用失败，可以返回空列表而不影响主流程：
async function getRecommendations(userId: string): Promise<Recommendation[]> { try { const result = await recommendationService.fetch(userId); return result; } catch (error) { console.warn('[降级] 推荐服务不可用，返回空列表:', error.message); // 监控告警：降级次数超过阈值需要人工介入 degradationCounter.inc({ service: 'recommendation' }); return []; } }策略三：熔断机制。当外部服务连续失败时，主动快速失败，避免资源耗尽。实现一个简单的熔断器：
class CircuitBreaker { private state: 'closed' | 'open' | 'half-open' = 'closed'; private failureCount = 0; private nextAttemptTime = 0; constructor( private readonly failureThreshold: number = 5, private readonly resetTimeoutMs: number = 60_000, ) {} async execute<T>(fn: () => Promise<T>): Promise<T> { if (this.state === 'open') { if (Date.now() < this.nextAttemptTime) { throw new ExternalServiceError('circuit-breaker', '熔断器开启，快速失败'); } this.state = 'half-open'; } try { const result = await fn(); this.onSuccess(); return result; } catch (error) { this.onFailure(); throw error; } } private onSuccess(): void { this.failureCount = 0; this.state = 'closed'; } private onFailure(): void { this.failureCount++; if (this.failureCount >= this.failureThreshold) { this.state = 'open'; this.nextAttemptTime = Date.now() + this.resetTimeoutMs; } } }踩坑记录：降级本身也可能出错
降级逻辑中的cache.get或console.warn也可能抛出异常（如 Redis 连接断开）。如果降级代码没有额外保护，会导致二次异常，反而让错误更难排查。正确的做法是降级逻辑本身也要有 try-catch：
async function fetchWithFallbackSafe<T>(fetcher: () => Promise<T>, cacheKey: string): Promise<T | null> { try { return await fetcher(); } catch (error) { // 降级逻辑本身也要捕获异常 try { const cached = cache.get(cacheKey); if (cached) return cached; } catch (cacheError) { console.error('[降级] 缓存读取失败:', cacheError); } return null; } }外部服务降级
interface CacheEntry<T> { data: T; timestamp: number; } async function fetchWithFallback<T>( fetcher: () => Promise<T>, cacheKey: string, fallbackValue: T | null = null, ttl: number = 300_000, // 5 分钟 ): Promise<T | null> { try { const data = await fetcher(); // 成功后缓存数据 cache.set(cacheKey, { data, timestamp: Date.now(), }); return data; } catch (error) { console.warn(`[fallback] 外部服务调用失败: ${error}`); // 尝试使用缓存数据 const cached = cache.get(cacheKey) as CacheEntry<T> | undefined; if (cached && Date.now() - cached.timestamp < ttl) { console.info(`[fallback] 使用缓存数据(key=${cacheKey})`); return cached.data; } // 缓存也无可用数据，返回指定的降级值 return fallbackValue; } }数据库连接池健康检查
import { Pool } from 'pg'; class DatabaseHealthCheck { private pool: Pool; private isHealthy = true; private checkInterval: NodeJS.Timeout | null = null; constructor(pool: Pool) { this.pool = pool; } start(intervalMs: number = 30_000): void { this.checkInterval = setInterval(async () => { try { await this.pool.query('SELECT 1'); this.isHealthy = true; } catch (error) { console.error('[DB Health] 连接检查失败:', error); this.isHealthy = false; } }, intervalMs); } async query(text: string, params?: unknown[]): Promise<unknown> { if (!this.isHealthy) { throw new ExternalServiceError('database', '连接池不健康'); } try { return await this.pool.query(text, params); } catch (error) { this.isHealthy = false; throw new ExternalServiceError( 'database', error instanceof Error ? error.message : '查询执行失败', ); } } stop(): void { if (this.checkInterval) { clearInterval(this.checkInterval); this.checkInterval = null; } } }进程级别的安全退出
import { Server } from 'http'; function setupGracefulShutdown(server: Server, pool: Pool): void { const shutdown = async (signal: string) => { console.info(`[Shutdown] 收到 ${signal} 信号，开始优雅退出`); // 步骤1：停止接收新请求 server.close(() => { console.info('[Shutdown] HTTP 服务已关闭'); }); // 步骤2：等待现有请求处理完成（最多 10 秒） const forceExit = setTimeout(() => { console.error('[Shutdown] 强制退出（超时）'); process.exit(1); }, 10_000); forceExit.unref(); // 步骤3：关闭数据库连接池 try { await pool.end(); console.info('[Shutdown] 数据库连接已关闭'); } catch (error) { console.error('[Shutdown] 数据库连接关闭失败:', error); } clearTimeout(forceExit); process.exit(0); }; process.on('SIGTERM', () => shutdown('SIGTERM')); process.on('SIGINT', () => shutdown('SIGINT')); // 兜底：未捕获异常立即退出 process.on('uncaughtException', (error) => { console.error('[Fatal] 未捕获异常:', error); process.exit(1); }); process.on('unhandledRejection', (reason) => { console.error('[Fatal] 未处理 Promise rejection:', reason); process.exit(1); }); }五、总结
Node.js 生产级错误处理的核心是"分类处理、统一出口、优雅降级"。通过自定义错误类体系区分操作性错误和程序性错误，前者可安全返回给客户端，后者只记录内部日志。统一错误处理中间件确保所有异常都有标准化的响应格式。外部依赖调用必须配备降级方案（缓存兜底或返回默认值）。进程级别的退出策略要保证：先停止接收新请求，再等待现有请求完成，最后清理资源。
