一个导出报表的接口,处理函数是 async 的,里面 await 了一个查询,然后抛出一个业务错误。本地请求一直转圈,直到浏览器提示超时;服务端日志里除了一行未处理的 Promise 拒绝,什么都没有。这就是 Express 4 时代最常见的事故:异步函数返回的 Promise 被拒绝时,框架不会自动调用错误中间件,请求就悬在那里。

换到 Express 5 后,同样的代码会被框架捕获并转交错误中间件,问题看起来解决了。可另一个接口仍然不返回统一错误体,排查半天才发现错误中间件写成了 (err, req, res) 三个参数。Express 靠函数参数个数识别错误中间件,少写一个 next,它就被当成普通中间件,永远不会处理错误。

还有一个更常见的顺序问题:为了统一 404,在文件开头写了 app.use((req, res) => res.status(404)...),结果所有接口都返回 404。请求确实进了中间件栈,但第一站就被兜底截住,后面的路由根本没机会执行。路由和中间件不是「写上去就生效」,它们的顺序就是程序逻辑本身。这篇把一次请求从进来到出去的每一步拆开,解释 Express 5 的匹配规则、Router 的挂载方式、请求体校验、异步错误和 CORS 预检,最后给一张能直接照着查的对照表。

一次请求穿过中间件栈

中间件是一个签名为 (req, res, next) 的函数,它可以读请求、改响应、结束响应,或者调用 next() 把控制权交给下一个。Express 把注册过的中间件和路由按顺序排成一个栈,请求进来后从栈顶往下走,直到有人结束响应或抛出错误。

本篇示例在 Node 24 下运行,依赖只有 Express 和 zod,启动脚本仍然是普通的 node:

{
  "name": "routing-lab",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node src/server.js",
    "dev": "node --watch src/server.js"
  },
  "dependencies": {
    "express": "^5.3.0",
    "zod": "^4.6.7"
  }
}

npm install express@5 zod@4
npm start
请求在 Express 中的生命周期
进入全局中间件
匹配挂载路径
进入 Router
执行路由处理函数
未结束则继续向下
404 或错误中间件

next() 不带参数表示「我没结束响应,继续」。带一个参数表示「出错了」,Express 会跳过所有普通中间件,直接寻找后面第一个四参数错误中间件。带字符串 'route' 表示跳过当前路由的剩余处理函数,进入下一个路由。这三种写法决定了控制流,写错一个,行为就完全不同。

还要注意 app.use 和 app.get 的匹配范围不同。app.use('/api', fn) 匹配的是前缀,/api、/api/orders、/api/orders/42 都会进入;app.get('/api', fn) 只匹配完全相同的路径。把中间件写成 app.get 是一种常见错误,表现是部分子路径不生效,开发者却以为中间件根本没注册。

注册顺序在代码里是自上而下的。下面的三段日志能直接看出顺序:先进入全局中间件,再进入挂在 /api 上的中间件,最后才到具体路由。

app.use((req, res, next) => {
  console.log('A: 全局中间件', req.method, req.path);
  next();
});

app.use('/api', (req, res, next) => {
  console.log('B: 挂在 /api 上');
  next();
});

app.get('/api/orders', (req, res, next) => {
  console.log('C: 路由处理函数');
  res.json({ items: [] });
});

请求 127.0.0.1:3201/api/orders 时,控制台依次打印 A、B、C,响应是:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"items":[]}

如果 B 里没有调用 next(),请求会停在 B,C 永远不执行,客户端只能等到超时。中间件不结束响应也不调用 next(),是「请求挂住」的最常见原因。排查时先看每个中间件是否在所有分支上都交了控制权。

404 兜底的位置决定它是不是灾难

兜底中间件本质上也是一个普通中间件,它之所以能兜住「所有没匹配的请求」,是因为它排在所有路由之后。Express 不会区分「兜底」和「业务」,它只按顺序匹配。把它写在前面,它就变成「拦截所有请求」。

正确的写法只有一种位置:所有路由和 Router 之后,错误中间件之前。它不需要路径参数,直接 app.use 即可。Express 5 里不要再用 app.all('*'),因为 * 已经不是合法路径;app.use 本身就能匹配所有方法和路径。

app.use((req, res) => {
  res.status(404).json({ error: 'not_found', path: req.path });
});

真实请求一个不存在的路径,返回:

curl -i 127.0.0.1:3201/nope

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"error":"not_found"}

如果这个中间件写在 app.get('/api/orders') 之前,同样的请求会先命中 404,路由永远轮不到。判断方法很直接:临时在 404 里打印当前路径,再访问一个本该存在的接口,如果它出现在 404 日志里,就是顺序错了。

用 Router 把路由拆开

路由变多后,把所有 app.get 堆在一个文件里会失控。Express 提供 Router,它是一组可以独立注册的路由和中间件,最后通过 app.use('/api/orders', router) 挂到一个前缀上。Router 内部的路径不需要重复写前缀,迁移和复用都更容易。

import { Router } from 'express';

export const ordersRouter = Router();

ordersRouter.get('/', (req, res) => {
  res.json({ items: [] });
});

ordersRouter.get('/:id', (req, res) => {
  res.json({ id: req.params.id });
});

ordersRouter.post('/', (req, res) => {
  res.status(201).json({ id: 1001 });
});

挂载时前缀只写一次:

import { ordersRouter } from './routes/orders.js';
app.use('/api/orders', ordersRouter);

这样 GET /api/orders、GET /api/orders/42、POST /api/orders 都会进入 Router。Router 上也可以挂只对本组生效的中间件,比如鉴权或限流,不会污染其他路由。第 4 篇的 requireAuth 就会挂在这一层。

Router 里写 '/' 和写空字符串效果一样,都表示前缀本身。但如果前缀带尾斜杠,strict routing 关闭时 /api/orders 与 /api/orders/ 都能匹配;开启后只认一种。团队最好统一约定,不要让两种写法混用。

express.json 的能力边界与 zod 校验

express.json() 只做一件事:把 JSON 请求体解析成 req.body。它不校验字段、不做类型转换、不知道业务规则。默认限制是 100kb,超了直接返回 413。这个限制很容易在真实业务里撞上,比如批量导入接口。

app.use(express.json({ limit: '1kb' }));

用一个超过 1kb 的 JSON 请求体实测,返回是:

HTTP/1.1 413 Payload Too Large

{"error":"payload_too_large","limit":"1kb"}

注意这条返回来自我们自己写的错误中间件,判断依据是 err.type === 'entity.too.large'。如果没写这个分支,客户端会拿到 Express 默认的 HTML 错误页。解析失败的错误类型还有 entity.parse.failed,对应非法 JSON,应该返回 400 而不是 500。

字段校验交给 zod。它是运行时校验库,用 TypeScript 或 JavaScript 描述形状,解析失败时给出一组结构化问题。把校验放在一个中间件里,路由里拿到的就是已经确认过的数据:

import { z } from 'zod';

const createOrderSchema = z.object({
  sku: z.string().min(1),
  qty: z.coerce.number().int().positive().max(99),
});

export function validateBody(schema) {
  return (req, res, next) => {
    const result = schema.safeParse(req.body);
    if (!result.success) {
      return res.status(400).json({
        error: 'validation_failed',
        issues: result.error.issues,
      });
    }
    req.body = result.data;
    next();
  };
}

传入 {"sku":"","qty":"0"} 时,zod 4 实际给出的问题数组是:

[
  {
    "origin": "string",
    "code": "too_small",
    "minimum": 1,
    "path": ["sku"],
    "message": "Too small: expected string to have >=1 characters"
  },
  {
    "origin": "number",
    "code": "too_small",
    "minimum": 0,
    "path": ["qty"],
    "message": "Too small: expected number to be >0"
  }
]

把 issues 原样返回给前端,调试方便,但会暴露内部字段名。面向外部用户的接口最好映射成稳定的错误码和中文提示;面向内部调用方可以保留细节。无论哪种,都要在文档里约定好,别让每个接口各写一套。

异步错误与 Express 5 的变化

Express 4 只识别同步抛错。处理函数是 async 时,抛出的错误变成被拒绝的 Promise,框架拿不到,只能等 Node 打印未处理拒绝。请求没有响应,客户端一直等,直到超时。老项目的补救办法是给每个 async 处理函数套一层 catch,或者引入 express-async-errors 之类的补丁。

Express 5 改掉了这一点:处理函数返回的 Promise 被拒绝时,会自动调用 next(err)。下面这个接口在第一篇的实例里实测,返回 500 和统一错误体:

app.get('/async-boom', async () => {
  await new Promise((r) => setTimeout(r, 10));
  throw new Error('async 抛错');
});

curl -i 127.0.0.1:3201/async-boom

HTTP/1.1 500 Internal Server Error

{"error":"internal_error","message":"async 抛错"}

但有一个边界必须记住:只有「处理函数返回的 Promise」会被捕获。如果你在 setTimeout 回调里抛错,或者在事件监听器里抛错,那不在 Promise 链上,Express 管不到。这类错误仍然会冒到进程级,处理不好会直接退出。

app.get('/timer-boom', (req, res) => {
  setTimeout(() => {
    throw new Error('这里抛错,Express 捕获不到');
  }, 0);
  res.json({ ok: true });
});

上面这个请求会先正常返回 {"ok":true},随后进程因为未捕获异常而崩溃。正确做法是把异步回调里的错误显式交给 next(err),或者在进程级注册 unhandledRejection 和 uncaughtException,记录日志后优雅退出。不要指望框架兜住所有异步错误。

Express 5 自动处理 Promise 拒绝,不等于可以随便写 async。在 forEach 里启动的异步任务、没有 await 的调用、事件回调里的异常,都不会进入错误中间件。排查「500 没日志」时,先确认错误是否真的在 Promise 链上。

四参数错误中间件与统一错误体

错误中间件的签名必须是四个参数:(err, req, res, next)。Express 靠 fn.length 判断,少一个就不被识别。这个规则不看参数名,只看个数,所以用下划线占位也有效。很多「错误中间件不生效」的问题,原因就是复制代码时删掉了没用的 next。

app.use((err, req, res, next) => {
  const status = err.status || 500;
  if (status >= 500) {
    console.error(JSON.stringify({ msg: 'request_failed', path: req.path, error: err.message }));
  }
  res.status(status).json({
    error: status >= 500 ? 'internal_error' : 'bad_request',
    message: status >= 500 ? '服务暂时不可用' : err.message,
  });
});

统一错误体至少要包含三样东西:稳定的错误码、人能看懂的提示、可追踪的请求标识。错误码给前端做分支,提示给人看,请求标识用来把客户端看到的现象和服务端日志对上。不要把堆栈返回给客户端,也不要把数据库原始错误直接透出。

错误中间件里有一个必须记住的分支:如果响应头已经发出去了,就不能再调用 res.status().json(),而应该把错误交给 next(err),让 Express 关闭连接。判断依据是 res.headersSent。很多「错误中间件自己也报错」的现场,都是因为流式响应写到一半失败,错误处理又试图写一个 JSON,结果触发第二次 Cannot set headers。

另一个常见错误是「响应已经发出去了,又写了一次」。下面的处理函数连续调用两次 res.json:

app.get('/twice', (req, res) => {
  res.json({ step: 1 });
  res.json({ step: 2 });
});

客户端实际收到的是第一次响应 {"step":1},第二次写入时 Express 会在日志里报 Cannot set headers after they are sent to the client。这个错误不会改变已经发出的响应,只会污染日志,严重时还会让进程进入不确定状态。排查时搜索这句话,重点看处理函数里是否有多个 res.json、res.send 分支,或者 next() 之后又写了响应。

CORS 预检:OPTIONS 为什么绕过了你的路由

浏览器跨域发 POST 且带 Content-Type: application/json 时,会先发一个 OPTIONS 预检请求。这个请求不带业务参数,只问「我能不能用这个方法和这些头」。如果服务端没有处理 OPTIONS,它会落到 404,浏览器随后拒绝真正的请求,控制台只显示一句笼统的 CORS 错误。

手写一个最小的 CORS 中间件不复杂,关键是它必须排在路由之前,并且对 OPTIONS 直接结束响应:

app.use((req, res, next) => {
  res.setHeader('Access-Control-Allow-Origin', 'http://localhost:5173');
  res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PATCH,DELETE');
  res.setHeader('Access-Control-Allow-Headers', 'content-type,authorization');
  res.setHeader('Access-Control-Max-Age', '600');
  if (req.method === 'OPTIONS') return res.sendStatus(204);
  next();
});

实测预检请求,返回 204 和一组允许头:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: GET,POST,PATCH,DELETE
Access-Control-Allow-Headers: content-type,authorization
Access-Control-Max-Age: 600

预检结果会被浏览器按 Access-Control-Max-Age 缓存。改了允许头之后,如果测试同学仍然看到旧的 CORS 报错,先让他清缓存或用无痕窗口,不要急着改服务端代码。缓存期内浏览器不会再发预检,服务端的修改根本还没被问到。

不要用 Access-Control-Allow-Origin: * 搭配 Access-Control-Allow-Credentials: true。浏览器会直接拒绝这种组合,而且带凭证的接口本来就不该对所有来源开放。生产环境应维护一份来源白名单,而不是反射请求里的 Origin。

NestJS 里同样的顺序长什么样

NestJS 11 把请求生命周期拆成更细的阶段,并规定了大致的执行顺序:中间件先执行,然后进入 Guard,再进入 Interceptor 的前半段,接着是 Pipe,之后才是控制器方法,返回时再经过 Interceptor 的后半段,异常最后落到 Exception Filter。这个顺序由框架保证,不依赖开发者把装饰器写在哪一行。

Express 的顺序靠注册

中间件、路由、错误处理都在一个数组里,谁先 app.use 谁先执行。鉴权写在校验中间件前面还是后面,完全由代码位置决定,框架不提醒。好处是透明,坏处是顺序散落在多个文件里,重构时容易错。

NestJS 的顺序靠约定

Guard 天然在 Pipe 之前,Pipe 天然在方法之前,Interceptor 天然包住方法。你只需要知道每个组件负责什么,不用手工排栈。代价是出问题时调用栈更长,要理解 DI 容器和装饰器元数据才能定位。

一个具体的差别:Express 里「解析请求体」是中间件,校验通常也写成中间件,两者谁先谁后要自己保证。NestJS 里请求体解析由平台适配器处理,Pipe 只负责转换和校验,顺序固定。团队如果经常在 Express 里把校验写在解析之前,导致 req.body 是 undefined,这种问题在 NestJS 的约定下不会出现。

现象、真实原因与第一步

现象真实原因第一步查什么
日志报 Cannot set headers after they are sent同一个请求写入了两次响应,或 next() 之后又写响应检查处理函数是否有多条 res.json 分支,在每次写响应前加日志
已存在的接口返回 404404 兜底注册在路由之前,或 Router 挂载前缀不匹配把 404 移到所有路由之后,打印 req.baseUrl 和 req.path
async 处理函数报错后请求挂住错误不在返回的 Promise 链上,或运行在 Express 4确认 Express 版本,检查 setTimeout、事件回调等游离异步
错误中间件写了但从不触发参数少于四个,被 Express 当成普通中间件确认签名是 (err, req, res, next),且注册在最后
500 响应里没有任何业务日志错误被默认处理器接住,或日志写在响应之后在错误中间件入口先打印 err.stack,再看日志采集是否丢掉 stderr
浏览器报 CORS,服务端看不到业务请求OPTIONS 预检落到 404,或缺少允许头用 curl 手动发 OPTIONS,看状态码和 Access-Control-Allow-*
请求体超过一点就 413express.json() 默认 100kb 限制看 err.type 是否为 entity.too.large,按接口调整 limit
非法 JSON 返回 500 或 HTML没有处理 entity.parse.failed,错误落到默认处理器在错误中间件按 err.type 分支,返回 400 JSON

边界与代价

中间件栈是一把双刃剑。三五层时,它像流水线,读代码就能看出请求经过哪些处理;十几层时,它变成金字塔,任何一个全局中间件都可能改变所有接口的行为。日志、鉴权、限流、CORS、请求体解析、压缩、缓存、追踪,每加一层都要重新评估顺序和性能。团队需要一条硬规则:全局中间件只放真正全局的东西,业务规则挂到 Router 上。

顺序耦合是另一个代价。两个中间件谁先谁后,往往没有写在文档里,只在某次提交里体现。排查时只能靠日志和断点。缓解办法是把关键顺序写成集成测试:比如「未登录请求必须返回 401 而不是 404」「非法 JSON 必须返回 400 而不是 500」,让顺序错误在 CI 里暴露。

Express 5 的兼容性也需要成本。路径语法变了,一些老中间件依赖的 req.param 被移除,错误处理行为也变了。升级前先盘点中间件清单,逐个确认支持 5.x,再在预发环境跑一遍关键链路。不要在生产直接改版本号。

最后,CORS 不是安全机制。它只约束浏览器的跨域读取,不阻止服务端到服务端的请求,也不阻止攻击者用 curl。真正的权限控制必须在服务端每个资源上判断,而不是靠一个响应头。

当天能自己验证的练习

  1. 按本文顺序注册 A、B、C 三个中间件,请求 /api/orders,确认日志顺序;再把 404 兜底移到最前面,观察同一个请求如何被截住。
  2. 写一个 async 路由,await 后 throw,确认返回 500 和统一错误体;再写一个在 setTimeout 里 throw 的路由,观察响应先成功、进程随后崩溃的差别。
  3. 把错误中间件改成三个参数,重启后请求一个会抛错的路由,确认它不再进入你的错误处理,而是落到 Express 默认响应。
  4. 用 curl 发 OPTIONS 预检,带上 Origin 和 Access-Control-Request-Method,确认返回 204;再注释掉 CORS 中间件,确认预检变成 404。
  5. 用 {"sku":"","qty":"0"} 调用带 zod 校验的接口,记录 issues 数组;再用一个 2kb 的请求体触发 entity.too.large,把 413 和 400 两条分支都跑一遍。

小结

三句话:中间件栈按注册顺序执行,next() 是唯一的控制权交接方式;404 和错误中间件的位置是硬约束,放错就全盘失效;Express 5 能接住 Promise 拒绝,但接不住游离在 Promise 链之外的异常。

下一篇进入数据层。路由和错误体确定后,处理函数里迟早要查数据库。连接池配多大、参数化查询怎么写、事务里的 await 为什么能把连接占死、迁移脚本怎么保证生产和测试一致,这些问题比路由顺序更难在本地复现。下一篇会用一台真实的 PostgreSQL 实例,把这些现象逐个跑出来。