Express中stream.pipe(res)传输大文件报500错误求助

你的问题核心是流式传输大文件时，流的异步错误未被正确捕获，导致服务器端无报错日志，但客户端直接收到500错误。file.createReadStream()返回的流属于异步事件驱动，外层的try/catch无法捕获这类异步错误——当大文件传输过程中出现网络波动、GCS连接中断等问题时，流会直接终止响应但不会进入你的catch块，最终客户端收到500。

同时还有几个潜在细节需要修正：

• file.exists()的判断应提前执行，避免无效的元数据请求
• meta[0].size是字符串类型，设置Content-Length时需要转为数字
• 未监听流的finish事件，无法确认传输是否正常完成

修改后的代码 #

app.get("/playlist/download/:ID", async (req, res) => {
  const id = req.params.ID;
  const fileName = `${playlist.getTitle(id)}.zip`;

  // 设置响应头
  res.setHeader('Content-Type', 'application/zip');
  res.setHeader('Content-Disposition', `attachment; filename="${fileName}"`);

  try {
    const file = playlistsBucket.file(`${id}.zip`);
    
    // 先判断文件是否存在，避免后续无效操作
    const [exists] = await file.exists();
    if (!exists) {
      return res.sendStatus(404);
    }

    // 获取元数据并设置正确的Content-Length（转为数字）
    const [meta] = await file.getMetadata();
    res.setHeader("Content-Length", Number(meta.size));

    const stream = file.createReadStream();

    // 关键：监听流的错误事件，捕获异步错误
    stream.on('error', (err) => {
      console.error('流式传输错误:', err);
      // 确保响应未发送时返回500，已发送则直接终止连接
      !res.headersSent ? res.sendStatus(500) : res.end();
    });

    // 可选：监听流结束事件，确认传输完成
    stream.on('finish', () => {
      console.log(`文件${fileName}传输完成`);
    });

    // 开始管道传输
    stream.pipe(res);
  } catch (err) {   
    console.error('请求处理错误:', err);
    // 避免重复发送响应
    if (!res.headersSent) {
      res.sendStatus(500);
    }
  }
});

额外排查建议 #

• 调整服务器超时时间：Express默认请求超时较短，大文件传输可能被中断，可通过server.timeout = 60000;（设置为60秒）延长超时
• 验证GCS权限：确保服务器使用的服务账号拥有storage.objects.get权限，权限验证失败也可能导致静默错误
• 捕获未处理异常：在代码顶部添加process.on('uncaughtException', (err) => console.error('未捕获异常:', err));，排查是否有漏抓的流错误

内容的提问来源于stack exchange，提问作者Tomáš Kordoš