Express中res.download回调抛出的错误为何无法被错误处理器捕获？

我搭建了基于Express 5.0.0-beta.1版本的服务器，并配置了极简错误处理器。通常应用中遇到错误时，我会抛出错误以让错误处理器捕获，但发现res.download()回调函数中抛出的错误无法被该处理器捕获。若手动调用next(err)则可被捕获，请问为何仅在此场景下抛出的错误会规避错误处理器？

代码示例 #

server.js #

...
app.use(api);
app.use((error, req, res, _next) => res.sendStatus(500));
...
app.listen(listenPort, () => {
  console.log(`\n--------------listening on: ${listenPort}-----------------\n`);
});

api.js #

router.get('/api/downloadFile', async (req, res, next) => {
  res.download('./mock.ts', 'myFile', (err) => {
    if (err) {
      throw err; // 👈👈👈👈 无法被错误处理器捕获，导致服务器崩溃
      // next(err) 👈👈👈👈👈 可被错误处理器捕获
    }
  });
});

res.download()的错误处理文档提示：

"响应可能已部分发送，因此请检查res.headersSent"

我猜测这是相关线索，但并不理解为何这会导致throw err与next(err)的行为差异。

核心原因在于Express的错误捕获机制只覆盖自身请求处理调用栈内的代码，而res.download()的回调执行时机已脱离该调用栈，具体拆解如下：

1. Express错误处理器的覆盖范围
   Express的全局错误处理器（带4个参数的中间件）仅捕获两类错误：

• 请求处理函数内同步抛出的错误；
• 主动调用next(err)传递的错误，无论调用位置是在请求处理函数内还是异步回调中。

但res.download()的回调属于底层文件操作/响应发送的异步逻辑，执行时已经不在Express为请求处理流程包裹的try/catch边界内。此时直接throw err会将错误抛到Node.js全局上下文，触发未捕获异常导致服务器崩溃。

2. res.headersSent提示的深层逻辑
   文档提到的res.headersSent是关键：res.download执行时可能已经向客户端发送了部分响应头或文件内容（比如流式传输启动后出错）。这种情况下，即使调用next(err)，Express也无法修改已发送的响应，但next(err)依然能将错误注入Express的错误处理流程，避免服务器崩溃；而直接throw则完全脱离管控，不受Express错误机制约束。

3. throw与next(err)的本质差异

• throw err：是JavaScript原生错误抛出，只有当前调用栈内的try/catch能捕获。若回调不在Express的try/catch范围内，错误会直接逃逸。
• next(err)：是主动触发Express的错误传递机制，无论回调处于什么异步上下文，都能将错误纳入Express的错误处理流程，被全局处理器接收。

解决方案 #

在res.download的错误回调中，始终使用next(err)传递错误，同时结合res.headersSent判断是否还能发送标准错误响应：

router.get('/api/downloadFile', async (req, res, next) => {
  res.download('./mock.ts', 'myFile', (err) => {
    if (err) {
      if (!res.headersSent) {
        next(err); // 响应未发送时，交给全局处理器返回500
      } else {
        // 响应已部分发送，仅记录错误，无法修改响应
        console.error('下载错误（响应已发送）:', err);
      }
    }
  });
});

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