Node.js使用Multer多字段接收上传文件时req.file返回undefined问题

req.file返回undefined的核心原因是Multer不同文件接收方法的请求挂载规则存在硬性差异，并非fileFilter或初始化配置错误。

• 你旧代码使用的.single('image')是单文件接收方法，处理完成后会将对应字段的单个文件直接挂载到req.file，因此旧逻辑可以正常读取文件数据。
• 你现在替换的.fields()是多字段、多文件接收方法，该方法不会在请求对象上生成req.file属性，所有通过校验的上传文件会按字段名分组，统一挂载到req.files对象上。

req.files的实际数据结构 #

无论某个字段实际上传了多少个文件，.fields()返回的文件结构都是以字段名为key的对象，每个key对应的value是文件数组，示例结构如下：

// 示例：传1张图到image字段、2个PDF到files字段时的返回结构
req.files = {
  image: [ { 图片文件的buffer、mimetype等元信息 } ],
  files: [ { PDF1元信息 }, { PDF2元信息 } ]
}

因为请求对象上不存在req.file键，直接取值自然会得到undefined。

根据业务场景可选择两种适配方式：

• 直接适配新的数据结构，从req.files按字段名取文件：
• 取image字段的图片：const uploadedImage = req.files?.image?.[0]，使用可选链可避免用户未传对应文件时报错
• 取files字段的附件列表：const uploadedDocs = req.files?.files || []，直接获取数组供后续邮件附件组装、云存储上传逻辑使用
• 如果不想改动后续所有读取req.file的旧业务逻辑，可在Multer中间件之后加一段兼容逻辑，手动将图片字段的文件挂载到req.file上：

app.use((req, res, next) => {
  // 兼容旧逻辑：将image字段的第一个文件挂载到req.file
  if (req.files?.image?.length) {
    req.file = req.files.image[0]
  }
  next()
})

• 你当前的.fields()配置未限制每个字段的上传文件数，建议补充maxCount参数做限制，比如image字段最多传1张、files字段最多传5个，避免前端误传多文件导致逻辑异常，配置示例：

  .fields([
    { name: 'image', maxCount: 1 },
    { name: 'files', maxCount: 5 }
  ])
  

• 排查问题时优先打印req.files查看实际上传结构，不要直接盯着req.file取值，可快速定位是字段名不匹配、文件被fileFilter拦截、还是前端传参字段不在配置列表中的问题。
• 当前fileFilter中被拦截的文件不会进入req.files数组，所有取值逻辑都需要做好空值判断，避免空指针错误。

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