React+NodeJS+Multer单文件上传失败问题排查

核心问题拆解 #

1. Node端Multer文件名配置完全错误 #

你想用req.body.file作为文件名，但Multer的逻辑是：文件上传解析优先级高于req.body，而且如果你的FormData里没单独传file字段，req.body.file本身就是空值。另外，Multer的文件名应该从上传的文件对象（req.file）里获取，不是从req.body拿。

2. React端FormData的文件名修改方式无效 #

文件对象的name属性是只读的，直接修改它再append到FormData不会生效，必须通过FormData的append参数指定自定义文件名。

3. 可能存在目录缺失问题 #

如果public/files目录不存在，Multer不会自动创建目录，会静默失败（不会抛错，但文件写不进去）。

4. 路由未正确绑定Multer中间件 #

如果你的/upload路由没配置Multer的upload.single()中间件，文件根本不会被解析，自然没有上传行为。

具体修复步骤 #

React端修正FormData构造 #

不要修改文件对象本身，append时通过第三个参数指定自定义文件名：

const handleSubmit = async () => {
  const formData = new FormData();
  // 生成带时间戳的文件名，保留原扩展名
  const timestamp = Date.now();
  const ext = file.name.split('.').pop();
  const newFileName = `${timestamp}.${ext}`;
  // 第三个参数就是传给后端的自定义文件名
  formData.append('uploadFile', file, newFileName);
  
  try {
    const res = await fetch('/upload', {
      method: 'POST',
      body: formData,
      // 不要手动设置Content-Type，浏览器会自动生成正确的multipart/form-data边界
    });
    console.log(res);
  } catch (err) {
    console.error(err);
  }
};

Node端修正Multer配置 #

1. 先确保目标目录存在，不存在则自动创建：

const fs = require('fs');
const uploadDir = './public/files';
if (!fs.existsSync(uploadDir)) {
  fs.mkdirSync(uploadDir, { recursive: true });
}

2. 正确配置Multer存储逻辑，从文件对象获取/生成文件名：

const multer = require('multer');

const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, './public/files');
  },
  filename: (req, file, cb) => {
    // 这里可以拿到React端传过来的自定义文件名（append时的第三个参数）
    cb(null, file.originalname);
    // 也可以在后端直接生成文件名：
    // const ext = file.mimetype.split('/')[1];
    // cb(null, `${Date.now()}.${ext}`);
  }
});

const upload = multer({ storage: storage });

// 路由必须绑定upload.single，参数要和React端append的字段名一致
app.post('/upload', upload.single('uploadFile'), (req, res) => {
  if (!req.file) {
    return res.status(400).json({ msg: '未检测到上传文件' });
  }
  res.json({ 
    msg: '上传成功',
    filePath: `/files/${req.file.filename}`
  });
});

额外排查点 #

• 配置静态资源访问：要让上传的文件能被访问，需要把public目录设为静态资源：

app.use(express.static('public'));

• Postman测试注意：选form-data格式，键名填uploadFile（和后端参数一致），再上传文件测试。
• 跨域问题：如果React和Node端口不同，必须配置CORS，否则请求可能看似成功但实际没传输文件。

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