使用express-fileupload时req.files始终为undefined的求助

以下是针对问题的具体排查步骤和解决方案，按优先级排序：

1. 检查中间件加载顺序（最常见原因） #

express-fileupload 必须在路由、bodyParser.json()/urlencoded() 之前加载，因为后者会提前解析请求体，导致文件上传的multipart数据被覆盖。

正确示例： #

const express = require('express');
const fileUpload = require('express-fileupload');
const app = express();

// 第一步加载文件上传中间件
app.use(fileUpload());

// 后续加载其他中间件（如静态文件、路由）
app.use(express.static('public'));
app.use('/api', require('./routes/upload'));

错误示例（会导致req.files为undefined）： #

// 先加载了bodyParser，会破坏multipart请求体
app.use(express.json());
app.use(fileUpload());

2. 修正客户端FormData构造 #

关键注意事项： #

• 不要手动设置Content-Type: multipart/form-data，浏览器会自动添加包含边界符的正确头部，手动设置会丢失边界信息，导致服务端无法解析文件。
• 确保文件字段名与服务端期望的一致。

正确客户端代码： #

const formData = new FormData();
// 字段名'uploadedFile'需与服务端req.files.uploadedFile对应
formData.append('uploadedFile', document.getElementById('fileInput').files[0]);

fetch('/api/upload', {
  method: 'POST',
  // 注释掉手动设置的Content-Type
  // headers: { 'Content-Type': 'multipart/form-data' },
  body: formData
})
.then(res => res.text())
.then(console.log);

3. 检查服务端路由配置 #

确保路由级别没有添加bodyParser类的中间件，否则会覆盖全局的fileUpload配置：

错误示例： #

// 路由级别的express.json()会解析请求体，导致文件丢失
app.post('/api/upload', express.json(), (req, res) => {
  console.log(req.files); // 必然是undefined
});

正确示例： #

app.post('/api/upload', (req, res) => {
  if (!req.files || Object.keys(req.files).length === 0) {
    return res.status(400).send('未上传任何文件');
  }

  // 处理文件
  const uploadedFile = req.files.uploadedFile;
  uploadedFile.mv(`./uploads/${uploadedFile.name}`, (err) => {
    if (err) return res.status(500).send(err);
    res.send('文件上传成功');
  });
});

4. 排查express-fileupload版本与配置 #

• 安装最新版本避免兼容性问题：

  npm install express-fileupload@latest
  

• 启用debug模式查看解析日志，定位问题：

  app.use(fileUpload({
    debug: true
  }));
  

• 检查文件大小限制，默认限制为50MB，若上传文件超出会导致req.files为undefined：

  app.use(fileUpload({
    limits: { fileSize: 100 * 1024 * 1024 }, // 调整为100MB
  }));
  

5. 验证请求内容 #

在浏览器开发者工具的Network标签中，查看POST请求的Form Data部分：

• 如果看不到文件条目，说明客户端代码未正确添加文件到FormData；
• 如果能看到文件条目，说明问题出在服务端中间件或路由配置。

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