Node.js Multer多文件上传遇404及ERR_HTTP_HEADERS_SENT错误求助

兄弟，你这个问题我太熟了！核心原因就是你的代码在一次请求里多次尝试给客户端发送响应，HTTP协议明确规定一个请求只能对应一个响应，所以服务器直接触发了错误。虽然图片成功上传到了uploads文件夹，但后续的重复响应操作搞崩了整个请求流程，才导致客户端收到404。

咱们一步步拆解解决：

1. 检查文件处理逻辑里的重复响应 #

最常见的坑就是在遍历上传文件时，不小心把res.send()/res.json()写到循环里了。比如这种错误写法：

// ❌ 错误：循环内发送响应，每处理一个文件就触发一次响应
app.post('/upload', upload.array('images', 2), (req, res) => {
  req.files.forEach(file => {
    // 处理文件（比如存路径到数据库）
    res.json({ msg: '文件上传成功' }); // 这里会多次调用响应，直接报错
  });
});

改成所有文件处理完成后，只发送一次响应：

// ✅ 正确：所有文件处理完毕后统一返回响应
app.post('/upload', upload.array('images', 2), (req, res) => {
  // 遍历处理所有上传的文件，收集必要信息
  const uploadedFiles = req.files.map(file => ({
    filename: file.filename,
    accessPath: `/uploads/${file.filename}`
  }));

  // 这里可以加存数据库等后续操作
  // saveFileRecords(uploadedFiles)...

  // 所有操作完成后，仅发送一次响应
  res.status(200).json({
    success: true,
    files: uploadedFiles
  });
});

2. 排查路由/中间件里的响应分支冲突 #

如果你的代码里有条件判断，要确保每个分支只执行一次响应，别出现多个分支都发送响应的情况。比如这种错误写法：

// ❌ 错误：两个分支都发送了响应
app.post('/upload', upload.array('images', 2), (req, res) => {
  if (req.files.length === 2) {
    res.send('两张图片上传成功');
  }
  // 这里又发送了一次响应，直接触发错误
  res.send('上传完成');
});

改成用return终止后续逻辑，保证只发一次响应：

// ✅ 正确：每个分支仅触发一次响应
app.post('/upload', upload.array('images', 2), (req, res) => {
  if (req.files.length === 2) {
    return res.status(200).send('两张图片上传成功');
  }
  res.status(200).send('上传完成');
});

3. 异步操作要等待全部完成再发响应 #

如果文件处理包含异步操作（比如压缩图片、写入数据库），一定要等所有异步任务都完成后再发送响应，不然会出现“先发送了响应，后续异步操作又尝试发送响应”的冲突。可以用Promise.all来批量处理异步任务：

// ✅ 异步操作的正确处理方式
app.post('/upload', upload.array('images', 2), async (req, res) => {
  try {
    // 把每个文件的异步处理包装成Promise
    const fileTasks = req.files.map(file => {
      return compressImage(file.path) // 比如压缩图片的异步函数
        .then(compressedPath => ({
          originalName: file.originalname,
          compressedPath
        }));
    });

    // 等待所有异步任务完成
    const processedFiles = await Promise.all(fileTasks);

    // 统一发送响应
    res.status(200).json({
      success: true,
      processedFiles
    });
  } catch (err) {
    // 捕获错误，仅发送一次错误响应
    res.status(500).json({
      success: false,
      error: err.message
    });
  }
});

4. 关于404错误的说明 #

当服务器触发ERR_HTTP_HEADERS_SENT错误时，整个请求流程会被中断，服务器无法正常返回正确的响应状态，所以客户端才会收到404。只要解决了重复发送响应的问题，404错误自然就会消失。

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