How to force all exceptions through a single middleware & serve a unified HTML Page for all errors?

在Web应用开发中，错误处理始终是决定用户体验的关键环节之一。传统上，开发者需要为不同类型的异常（如404、500、自定义业务异常）分别编写处理逻辑，导致代码冗余、维护困难。近期，一种通过单一中间件强制捕获所有异常并渲染统一HTML错误页面的实践方案在开发者社区引发热议。本文将详细解析这一模式的实现原理、优势及具体编码步骤。

一、为何需要统一异常中间件？

现代Web框架（如Express、Koa、Django等）均提供中间件机制，但默认的错误处理往往分散在各路由或控制器中。当项目规模扩大，团队协作时容易遗漏某些异常处理，导致用户看到“白页”或原始堆栈信息，既不安全也不友好。

核心痛点： - 重复代码：每个错误响应都需手动设置状态码、渲染模板。 - 不一致体验：不同错误返回不同HTML结构，用户困惑。 - 安全隐患：未捕获的异常可能泄露敏感路径、数据库信息。

统一中间件方案旨在将所有未处理异常（包括同步错误和异步Promise reject）导向同一处理函数，自动生成风格统一的错误页面。

二、核心实现逻辑

以Node.js Express框架为例，具体步骤如下：

1. 定义全局错误中间件

Express中间件有四个参数（err, req, res, next），当任意中间件或路由中调用next(err)或抛出异常时，错误会传递至此。

// errorHandler.js
module.exports = (err, req, res, next) => {
  // 记录日志（可接入日志系统）
  console.error('Unhandled Error:', err);

  // 设置HTTP状态码（优先使用err.status，默认500）
  const statusCode = err.status || err.statusCode || 500;

  // 渲染统一HTML页面
  res.status(statusCode);
  res.render('error', {
    title: `错误 ${statusCode}`,
    message: err.message || '服务器内部错误',
    stack: process.env.NODE_ENV === 'development' ? err.stack : null
  });
};

2. 强制捕获异步异常

Express 4中，异步路由内的Promise reject不会自动触发错误中间件。需使用包装函数或Express 5的async支持。常用做法：

const asyncHandler = fn => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

// 路由中使用
app.get('/user/:id', asyncHandler(async (req, res) => {
  const user = await getUser(req.params.id);
  if (!user) {
    const err = new Error('用户不存在');
    err.status = 404;
    throw err;  // 将被asyncHandler捕获并传给next(err)
  }
  res.json(user);
}));

3. 放置中间件顺序

统一错误中间件必须注册在所有路由和中间件之后，否则无法捕获前序环节的错误。

app.use('/api', apiRouter);
app.use('/', viewRouter);
// 错误中间件必须在最后
app.use(errorHandler);

4. 设计统一错误页面模板

创建一个views/error.ejs（或任何模板引擎），使用一致布局，包含状态码、友好提示、可选的开发环境堆栈信息。

<!DOCTYPE html>
<html>
<head><title><%= title %></title></head>
<body>
  <div style="text-align:center;padding:80px;">
    <h1><%= statusCode %></h1>
    <p><%= message %></p>
    <% if (stack) { %>
      <pre style="white-space:pre-wrap;text-align:left;"><%= stack %></pre>
    <% } %>
    <a href="/">返回首页</a>
  </div>
</body>
</html>

三、扩展：服务端渲染以外的应用

该模式同样适用于REST API场景，只需将渲染HTML改为返回JSON：

// 内容协商：根据请求头决定响应格式
if (req.accepts('html')) {
  res.render('error', { ... });
} else {
  res.json({ error: err.message });
}

另外，可结合express-rate-limit、helmet等中间件，增强安全性。

四、最佳实践与注意事项

不要吞掉错误：始终确保错误中间件被调用，避免使用空catch块。
区分环境：生产环境禁止返回堆栈信息，可通过NODE_ENV控制。
自定义错误类：继承Error，添加status属性，简化判断。
配合日志系统：生产环境应接入Sentry、Winston等，记录错误详情。
测试覆盖：编写针对错误中间件的单元测试，验证不同异常场景。

五、结语

单一错误中间件是构建健壮Web应用的基石。它通过集中处理逻辑，既保证了用户体验的一致性，又降低了安全风险。无论你使用的是Node.js、Python Flask还是Go Gin，这一思想均可迁移。根据框架文档适配实现，你将获得一个优雅、可维护的错误处理体系。

附录：常用框架参考链接 - Express Error Handling - Koa Error Handling - Django Custom Error Views

（全文约980字）

How to force all exceptions through a single middleware &amp; serve a unified HTML Page for all errors?