Node.js ERR_HTTP_HEADERS_SENT — 响应头已发送

诊断并修复 Node.js 的 ERR_HTTP_HEADERS_SENT：同一请求在响应头已发送后再次尝试设置响应头。

症状

服务端抛出 ERR_HTTP_HEADERS_SENT，客户端收到的响应被截断或干脆挂起。该错误常常只在某个分支或高并发下出现，而非每个请求都触发。

先在路由及其辅助函数中搜索所有写响应的调用，检查每个分支是否遗漏了 return。然后在每次写入之前打印 res.headersSent：

if (res.headersSent) {
  console.warn('skipping second response');
  return;
}

最快的复现方式是让一个处理函数先响应，随后又 await 一个同样调用 res.json() 的回调——此时第二次写入就会触发该错误。

确保每个请求只有一个响应生效。让所有分支以 return 结束，用 headersSent 守卫保护异步续段；错误中间件在已有写入时必须放弃再次响应：

return res.status(500).json({ error: 'boom' });

开启日志后重新请求该端点，应当只看到一次响应写入且不再抛出 ERR_HTTP_HEADERS_SENT。对路由做并发压测可确认该错误在高负载下也已消失。