Express 错误处理：错误中间件与异步错误

Express 用一种特殊的中间件处理错误：它接收四个参数 (err, req, res, next)，并且注册在所有路由之后。路由中抛出的每个错误、你传给 next(err) 的每个错误，以及在 Express 5 中 async 处理函数里每个被拒绝的 Promise，Express 都会交给它。由这个处理器决定状态码并发送一个错误响应，其余代码只管抛出错误就行。

const express = require('express');
const app = express();

const users = [{ id: 1, name: 'Ada' }];

app.get('/users/:id', (req, res) => {
    const user = users.find((u) => u.id === Number(req.params.id));
    if (!user) {
        const err = new Error(`No user with id ${req.params.id}`);
        err.status = 404;
        throw err;
    }
    res.json(user);
});

// The error handler: four arguments, after the routes.
app.use((err, req, res, next) => {
    console.log('error handler:', err.message);
    res.status(err.status ?? 500).json({ error: err.message });
});

// GET /users/99
app.listen(3000);

GET /users/99 返回 404 和 {"error":"No user with id 99"}，控制台里会出现错误处理器打印的那一行。发送 GET /users/1，路由会正常响应；只有出问题时才会运行错误处理器。

Express 帮你捕获的错误

从路由进入错误处理器有三种方式，在 Express 5 中三者的效果完全一样：

// Each route throws on purpose to reach the error handler.
const express = require('express');
const app = express();

app.get('/sync', (req, res) => {
    throw new Error('Thrown in a route');
});

app.get('/next', (req, res, next) => {
    next(new Error('Passed to next()'));
});

app.get('/async', async (req, res) => {
    await new Promise((resolve) => setTimeout(resolve, 10));
    throw new Error('Rejected in an async route');
});

app.use((err, req, res, next) => {
    res.status(500).json({ error: err.message });
});

// GET /async
app.listen(3000);

GET /async 返回 500 和 {"error":"Rejected in an async route"}；GET /sync 和 GET /next 也会进入同一个处理器，各自带着自己的消息。现在把错误处理器参数里的 next 删掉，再发送一次 GET /sync：只有三个参数时，Express 会把它当作普通中间件而跳过，转而返回默认的 HTML 错误页面。

异步错误：Express 5 与 Express 4

/async 路由能正常工作，是因为 Express 5 会捕获被拒绝的 Promise。Express 4 不会：这个错误会变成未处理的 rejection，请求一直挂起。

在 Express 4 中，要给每个异步处理函数包一层，或者安装 express-async-errors 包：

// Express 4 only
const asyncHandler = (fn) => (req, res, next) =>
    Promise.resolve(fn(req, res, next)).catch(next);

app.get('/users/:id', asyncHandler(async (req, res) => {
    const user = await db.findUser(req.params.id);
    res.json(user);
}));

最后一行在两个版本中都一样：Express 看不到在一个不由它调用的回调里抛出的错误。把回调式 API 换成 Promise 版本（Node 的大部分功能都有 Promise 版本，比如 fs/promises），然后用 await 调用。

404 处理器和统一的 JSON 错误

当每个错误的结构都一样时，API 会更好用。给错误加上 status，把没有匹配到的路由变成 404 错误，然后让一个处理器统一格式化所有错误：

const express = require('express');
const app = express();
app.use(express.json());

class HttpError extends Error {
    constructor(status, message) {
        super(message);
        this.status = status;
    }
}

const users = [{ id: 1, name: 'Ada' }];

app.get('/users/:id', (req, res) => {
    const user = users.find((u) => u.id === Number(req.params.id));
    if (!user) throw new HttpError(404, `No user with id ${req.params.id}`);
    res.json(user);
});

app.post('/users', (req, res) => {
    if (!req.body?.name) throw new HttpError(400, 'name is required');
    res.status(201).json({ id: 2, name: req.body.name });
});

// 404: no route matched.
app.use((req, res, next) => {
    next(new HttpError(404, `Cannot ${req.method} ${req.path}`));
});

app.use((err, req, res, next) => {
    if (res.headersSent) return next(err);
    const status = err.status ?? 500;
    if (status >= 500) console.log(err);
    res.status(status).json({
        error: status >= 500 ? 'Internal server error' : err.message,
        status,
    });
});

// GET /nope
app.listen(3000);

GET /nope 没有匹配到任何路由，所以 404 处理器把它变成一个错误，响应是 {"error":"Cannot GET /nope","status":404}。发送 GET /users/99，路由抛出的错误也会得到同样的结构。发送 POST /users，请求体为 {"name": }：express.json() 解析失败，会带着一个 status 为 400 的错误调用 next()，所以响应是 {"error":"Unexpected token '}', \"{\"name\": }\" is not valid JSON","status":400}。

不要泄露堆栈信息

你自己的 HttpError 中的错误消息是写给客户端看的。其他来源（数据库驱动、一个抛出 TypeError 的拼写错误）的消息和堆栈可能会暴露文件路径、查询语句和库的版本。上面的处理器对每个 5xx 都只发送 Internal server error，而把真正的错误记录在服务器上。if (res.headersSent) return next(err); 处理的是响应已经发出一部分之后才发生的错误：这时唯一安全的做法就是让 Express 关闭连接。

Express 自带的默认处理器会参考 NODE_ENV：除非 NODE_ENV 是 production，否则它的 HTML 页面里会包含堆栈信息。在生产服务器上设置它（NODE_ENV=production node server.js），但不要依赖它：一个永远不发送 err.stack 的自定义处理器更安全。

常见错误

在路由之前注册错误处理器。 Express 只会把错误往后传，所以位于某个路由之前的处理器永远看不到这个路由的错误。把它放在最后，放在 404 处理器之后。

捕获了错误却什么都不做。 只记录日志的 try/catch 会让请求一直挂起。在 catch 中调用 next(err)、重新抛出，或者发送一个响应。

发送两次响应。 在 res.json() 之后再抛出错误，会让错误处理器尝试再发送一次。像示例中那样检查 res.headersSent。

想了解普通中间件和 next() 的工作方式，请看 Express 中间件。