NestJS使用@Res响应时出现ERR_HTTP_HEADERS_SENT错误相关问题咨询

错误根因 #

该错误本质是同一个HTTP请求周期内多次发送响应、修改已发送的响应头导致的。Express 中res.json()方法本身会隐式调用res.send()完成响应发送并终止当前请求，初始代码中链式追加的.send()属于重复调用响应发送逻辑。

初始错误代码 #

@Get()
get(@Req() req, @Res() res) {
  const result = this.service.getData(req);
  // 错误点：res.json()已经隐含send操作，重复调用send会触发二次响应发送
  res.status(result.statusCode).json(result.data).send();
}

修复后代码 #

@Get()
get(@Req() req, @Res() res) {
  const result = this.service.getData(req);
  res.status(result.statusCode).json(result.data);
  // 终止方法执行，避免Nest后续内置逻辑操作响应
  return;
}

疑问1：是否必须在控制器方法末尾添加return;？ #

• 当你通过@Res()注入原生Express响应对象时，NestJS默认会将响应的控制权转交给开发者，但框架内置的拦截器、响应序列化逻辑、异常过滤器依然会在控制器方法执行完成后按序运行。
• 末尾加return;的作用是明确终止控制器方法的执行，避免Nest的默认处理逻辑尝试操作已经被发送完成的响应对象，触发二次修改的错误。
• 它不属于语法强制要求，但属于手动操作原生响应时的最佳实践，可以完全避免框架内置逻辑和手动响应操作的冲突。

额外优化建议：如果只是需要自定义状态码、响应头，不需要完全接管响应，可以使用@Res({ passthrough: true })注入响应对象，直接return业务数据即可，Nest会自动完成响应序列化发送，不需要手动调用res.json()，也能避免这类重复发送响应的问题。

疑问2：为什么调用.send()只会偶尔触发错误而非必现？ #

• ERR_HTTP_HEADERS_SENT错误的触发有严格的时机条件：只有当第一次响应已经完全写入系统网卡缓冲区、并发送到客户端之后，第二次尝试修改响应头或者发送响应内容才会抛出该错误。
• res.json()方法本身就会隐式调用res.send()完成响应发送，额外链式调用的.send()属于重复的响应发送操作。如果两次操作的间隔极短，第一次响应还停留在Node.js内部的I/O缓冲区没有被刷出到网卡，Express内部会直接忽略第二次无效的send()调用，不会触发错误。
• 报错的偶发性还和当前服务器的CPU负载、网络IO延迟强相关：服务器负载高、网络慢的时候，响应刷出到客户端的速度慢，第二次send()大概率会被忽略；服务器空闲、网络快的时候，响应很快就完成发送，第二次send()就会触发错误。

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