Express错误处理中Node.js触发Headers already sent错误崩溃排查

错误原因 #

Error [ERR_HTTP_HEADERS_SENT]: Cannot set headers after they are sent to the client 错误的核心原因是：代码尝试向客户端发送多次HTTP响应。第一次响应已经完成发送（比如某个分支的res.json），后续又有代码触发了第二次响应操作，导致Node.js抛出这个错误。

排查与解决步骤 #

1. 检查路由是否重复注册 #

确认你的注册路由（比如app.post('/register', registerUser)）只被定义了一次。如果路由被重复注册，同一个请求会触发两次registerUser执行，第一次发送响应后，第二次再发送就会报错。

2. 检查路由挂载的额外中间件 #

如果注册路由时附加了其他中间件（比如app.post('/register', registerUser, otherMiddleware)），确保后续中间件不会调用res.send/res.json等响应方法，或者在当前registerUser函数中通过return明确终止请求流程，避免后续中间件继续执行。

3. 优化全局错误处理中间件（如果存在） #

如果项目中有全局错误处理中间件，必须先判断响应是否已经发送，避免重复响应：

app.use((err, req, res, next) => {
  // 若响应已发送，直接传递错误到Express默认处理逻辑
  if (res.headersSent) {
    return next(err);
  }
  // 未发送响应时，统一处理错误
  res.status(500).json({ status: 'fail', message: 'Server error' });
});

4. 增加日志排查执行路径 #

在每个响应发送前添加日志，确认代码是否多次进入响应分支：

const registerUser = async (req: Request, res: Response) => {
  try {
    const userData = createUserSchema.parse(req.body) as User;

    const salt = await bcrypt.genSalt(10);
    const hashedPassword = await bcrypt.hash(userData.password, salt);

    const user = await db.user.create({
      data: {
        ...userData,
        password: hashedPassword,
      },
    });

    console.log('发送成功响应');
    return res.status(201).json({
      status: 'success',
      data: { name: user.name, email: user.email },
    });
  } catch (error) {
    console.error('注册错误详情:', error);
    
    if (error instanceof z.ZodError) {
      console.log('发送参数验证错误响应');
      return res.status(422).json({
        status: 'fail',
        message: error.issues,
      });
    } else if (error instanceof Prisma.PrismaClientKnownRequestError) {
      if (error.code === 'P2002') {
        console.log('发送邮箱重复错误响应');
        return res.status(409).json({
          status: 'fail',
          message: 'Email address is already in use',
        });
      }
    }

    console.log('发送服务器内部错误响应');
    return res.status(500).json({
      status: 'fail',
      message: 'Something went wrong',
    });
  }
};

通过日志可以清晰看到是否有多次发送响应的情况，定位问题根源。

5. 确认异步错误捕获完整性 #

虽然代码用try/catch包裹了所有异步操作，但可以补充捕获未知错误类型的处理，避免遗漏导致的隐性问题：

catch (error) {
  // ...原有错误判断逻辑
  // 兜底处理所有未匹配的错误
  console.error('未捕获的错误类型:', error);
  return res.status(500).json({
    status: 'fail',
    message: 'Something went wrong',
  });
}

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