使用Multer结合AWS S3 SDK v3上传文件失败，请求报错如何排查？

问题根源 #

你遇到的核心问题是multer-s3默认适配AWS SDK v2，与v3的S3Client不兼容，导致上传过程中抛出未被捕获的错误，multer内部提前发送了错误响应，后续createDocument中间件再尝试发送响应时就会触发"Cannot set headers after they are sent to the client"错误。

修复方案 #

方案1：使用兼容SDK v3的multer-s3替代包

安装专门适配v3的multer-s3-v3包：

npm install multer-s3-v3

修改控制器代码：

const { S3Client } = require("@aws-sdk/client-s3");
const multer = require("multer");
const multerS3 = require("multer-s3-v3");

const s3 = new S3Client({
  credentials: {
    accessKeyId: "myid",
    secretAccessKey: "mykey",
  },
  region: "us-east-2",
});

const s3Storage = multerS3({
  s3: s3,
  bucket: "mybucket",
  acl: "public-read",
  metadata: (req, file, cb) => {
    cb(null, { fieldname: file.fieldname });
  },
  key: (req, file, cb) => {
    cb(null, Date.now().toString());
  },
});

const upload = multer({ storage: s3Storage });
exports.uploadFile = upload.single("file");

exports.createDocument = catchAsync(async (req, res, next) => {
  // 注意：multer-s3-v3中，S3存储的文件名存在req.file.key而非filename
  const newDoc = await Model.create({
    title: req.body.title,
    file: req.file.key,
  });
  res.status(201).json({
    status: "success",
    data: { data: newDoc },
  });
});

方案2：手动实现内存上传+SDK v3 Upload API（更灵活）

若不想依赖第三方包，可先用multer将文件暂存内存，再用AWS SDK v3的Upload工具完成上传：

const { S3Client } = require("@aws-sdk/client-s3");
const { Upload } = require("@aws-sdk/lib-storage");
const multer = require("multer");

const s3 = new S3Client({
  credentials: {
    accessKeyId: "myid",
    secretAccessKey: "mykey",
  },
  region: "us-east-2",
});

// 用multer将文件暂存内存
const storage = multer.memoryStorage();
const upload = multer({ storage: storage });

exports.uploadFile = upload.single("file");

exports.createDocument = catchAsync(async (req, res, next) => {
  if (!req.file) return next(new Error("未上传文件"));

  const fileName = Date.now().toString();
  // 用SDK v3的Upload处理大文件分片上传
  const uploadParams = {
    Bucket: "mybucket",
    Key: fileName,
    Body: req.file.buffer,
    ACL: "public-read",
    Metadata: { fieldname: req.file.fieldname },
  };

  try {
    const uploadTask = new Upload({
      client: s3,
      params: uploadParams,
    });
    await uploadTask.done();
  } catch (err) {
    return next(err);
  }

  const newDoc = await Model.create({
    title: req.body.title,
    file: fileName,
  });

  res.status(201).json({
    status: "success",
    data: { data: newDoc },
  });
});

调试技巧 #

• 给uploadFile中间件添加错误捕获，避免multer内部直接发送响应：

  exports.uploadFile = (req, res, next) => {
    upload.single("file")(req, res, (err) => {
      if (err) {
        return res.status(400).json({ status: "error", message: err.message });
      }
      next();
    });
  };
  

• 检查AWS凭证权限：确保IAM用户拥有s3:PutObject和s3:PutObjectAcl权限，否则上传会失败。
• 验证S3存储桶CORS配置：若为前端直传请求，需配置正确的CORS规则；若为后端代理上传，确保后端服务器可正常访问S3服务。

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