Express中Multer单文件上传异常：req.files未正确填充

问题场景 #

在Express项目里用Multer处理文件上传，把maxCount设为1后出了问题：

• 预期：传单个文件时，req.files应该能拿到文件信息并生成对应URL
• 实际：单文件上传时req.files要么没数据要么不对，URL生成失败；传两个文件时，第一个文件的URL能正常生成

测试用的是Postman，涉及Controller逻辑、Multer中间件配置和路由规则。

问题原因 #

Multer的array()或fields()方法有个默认行为：当maxCount设为1，且实际只传单个文件时，req.files会返回单个文件对象，而不是数组。如果你的代码是按照req.files是数组来写的，自然拿不到数据。

解决办法 #

在Controller里统一处理req.files的格式，不管是单文件还是符合maxCount的多文件，都转成数组来处理：

1. 调整Controller逻辑 #

// 示例Controller代码
const uploadHandler = (req, res) => {
  // 把req.files转为数组，适配单/多文件场景
  const targetFiles = Array.isArray(req.files.yourFieldName) 
    ? req.files.yourFieldName 
    : [req.files.yourFieldName];

  // 生成文件URL的逻辑
  const fileUrls = targetFiles.map(file => {
    return `${req.protocol}://${req.get('host')}/uploads/${file.filename}`;
  });

  res.status(200).json({
    msg: '上传成功',
    urls: fileUrls
  });
};

2. 确认Multer配置 #

确保你的Multer中间件用的是array()（单字段多文件）或fields()（多字段）配置，比如：

const multer = require('multer');
const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, './uploads'); // 上传文件存储目录
  },
  filename: (req, file, cb) => {
    cb(null, Date.now() + '-' + file.originalname); // 重命名避免冲突
  }
});

const upload = multer({
  storage: storage,
  limits: { fileSize: 5 * 1024 * 1024 } // 可选：限制单文件大小为5MB
});

// 路由配置，字段名要和前端/Postman里的一致，比如这里是'uploadFiles'
router.post('/upload', upload.array('uploadFiles', 1), uploadHandler);

3. Postman测试注意点 #

• 单文件上传时，表单字段名要和路由里array()的第一个参数完全一致
• 不要勾选文件输入框的「Multiple」选项，直接上传单个文件即可

验证效果 #

修改后重新测试：

• 单文件上传：req.files会被转为数组，正常生成URL
• 传两个文件：Multer会自动过滤第二个文件（因为maxCount=1），只保留第一个，处理逻辑正常执行

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