Node.js从AWS S3批量下载文件报‘write after end’错误求排查解决

根因分析 #

这个错误的核心问题在于，你在同一个HTTP响应对象（res）上重复执行了写入/结束操作。单个文件下载时，写完内容后响应流会正常关闭；但批量下载时，循环处理后续文件时还在往已经关闭的res里写入数据，自然触发了"write after end"的报错——就像你关了水龙头之后还试图往水管里灌水一样。

解决方案：用Zip流打包批量文件后返回 #

如果需求是让用户一次性下载多个文件，最合理的方式是把这些文件打包成Zip包，通过单个响应返回。下面是修改后的代码示例，使用archiver库处理Zip打包：

首先安装依赖：

npm install archiver

然后更新你的下载函数：

var AWS = require('aws-sdk');
var archiver = require('archiver');

module.exports.download = function (req, res) {
    var S3_BUCKET = 'mybucketname';
    var s3 = new AWS.S3({
        // 补充你的S3配置，例如region、credentials等
    });

    // 假设你要下载的文件列表存在这里，比如 ['docs/report.pdf', 'images/avatar.png']
    const targetFileKeys = req.body.fileKeys;

    // 设置响应头，告诉浏览器这是一个可下载的Zip文件
    res.setHeader('Content-Type', 'application/zip');
    res.setHeader('Content-Disposition', `attachment; filename="batch-files.zip"`);

    // 创建Zip归档流，设置压缩级别
    const zip = archiver('zip', { zlib: { level: 9 } });

    // 将Zip流关联到响应对象
    zip.pipe(res);

    // 监听Zip流的错误，避免进程崩溃
    zip.on('error', (err) => {
        res.status(500).send(`打包失败：${err.message}`);
    });

    // 遍历文件列表，逐个从S3拉取并加入Zip
    targetFileKeys.forEach(key => {
        // 从S3获取文件的可读流
        const s3FileStream = s3.getObject({ Bucket: S3_BUCKET, Key: key }).createReadStream();
        // 将文件流加入Zip，第二个参数是Zip内显示的文件名
        zip.append(s3FileStream, { name: key.split('/').pop() });
    });

    // 结束Zip流，触发打包并向客户端返回数据
    zip.finalize();
};

方案为什么有效？ #

• 我们只对res执行一次流关联操作，所有文件先写入Zip归档流，再统一通过res返回，彻底避免了重复写入已关闭响应流的问题。
• archiver会自动处理多流的合并、错误捕获和结束逻辑，不用手动管理每个文件的流状态。

特殊场景说明 #

如果你的需求不是打包下载（这种场景非常少见，不符合常规HTTP交互逻辑），你需要改为返回多个独立响应，或者使用WebSocket等方式传输文件，但优先推荐Zip打包的方案，这是最符合用户下载习惯的实现方式。

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