Express生成器创建的Node.js应用：错误捕获时res.locals变量未定义咨询

这个问题我之前在项目里也踩过坑，核心原因和Express的中间件执行顺序、res.locals的生命周期，以及错误处理机制密切相关，下面拆解具体原因和解决办法：

常见原因 #

1. 错误发生在res.locals变量设置之前 #

Express的中间件是按顺序执行的，如果错误在设置res.locals.user/config的中间件之前就被抛出，那这些变量根本没机会被初始化。举个例子：

// app.js
app.use(express.json()); // 这里如果解析请求体出错（比如JSON格式错误）
app.use((req, res, next) => {
  res.locals.user = req.user; // 这个中间件根本没执行
  res.locals.config = app.get('config');
  next();
});
app.use('/', routes);

这种情况下，错误会直接跳到最后的错误处理中间件，此时res.locals里自然没有user和config。

2. 错误处理中间件意外清空了res.locals #

很多人写错误处理中间件时，会不小心覆盖整个res.locals对象，比如：

// 错误写法：直接替换res.locals，清空之前的所有变量
app.use((err, req, res, next) => {
  res.locals = {
    message: err.message,
    error: err
  };
  res.render('error');
});

这种操作会把之前设置的user、config全部清空，导致访问时返回undefined。

3. 异步错误未正确传递给next() #

如果你的路由或中间件是异步函数，抛出错误时没有用next(err)传递，Express无法将错误引导到错误处理中间件，甚至可能导致响应上下文异常。比如：

// 错误写法：异步函数抛出错误但未处理
router.get('/', async (req, res) => {
  await someAsyncFunc(); // 如果这里出错，错误会变成未处理的Promise拒绝
  throw new Error('Something went wrong');
});

这种情况下，Express的错误处理机制无法正常捕获错误，res.locals的状态可能会因为响应异常而被重置。

4. 错误发生时响应已被发送 #

如果在错误抛出前已经调用了res.send()、res.render()等方法，响应头已经发送，此时res对象的状态会被标记为已完成，res.locals可能会被销毁或重置，后续错误处理中间件访问时就会得到undefined。

解决办法 #

• 调整中间件顺序：确保设置res.locals变量的中间件放在所有可能抛出错误的中间件（比如解析器、路由）之前，保证无论是否出错，这些变量都能被初始化。
• 正确处理异步错误：在异步路由/中间件中用try-catch捕获错误并传递给next(err)，或者使用express-async-errors库自动处理异步错误：

  router.get('/', async (req, res, next) => {
    try {
      await someAsyncFunc();
      throw new Error('Something went wrong');
    } catch (err) {
      next(err); // 把错误传递给错误处理中间件
    }
  });
  

• 避免覆盖res.locals：在错误处理中间件中，只添加或修改需要的属性，不要直接替换整个对象：

  // 正确写法
  app.use((err, req, res, next) => {
    res.locals.message = err.message;
    res.locals.error = req.app.get('env') === 'development' ? err : {};
    // 之前的user、config依然存在
    res.status(err.status || 500);
    res.render('error');
  });
  

• 检查响应状态：在错误处理中间件中先判断res.headersSent，如果响应已发送，直接调用next(err)让Express处理：

  app.use((err, req, res, next) => {
    if (res.headersSent) {
      return next(err);
    }
    // 后续错误处理逻辑
  });
  

内容的提问来源于stack exchange，提问作者EmaMaMaso EmaSeMa