React与Express实现图片上传时的问题排查及解决方法

问题背景 #

我在搭建 React + Express 图片上传功能时踩了坑：前端用 FileReader 实现了图片实时预览，但后端通过 Multer 处理上传时，req.file 始终返回 undefined，完全无法接收文件。

先贴出我最初的实现代码：

前端 React 代码

// 读取图片并保存base64编码用于预览
uploadImage = (e) => { 
  const reader = new FileReader(); 
  reader.onload = (e) => { 
    if (reader.readyState === 2) { 
      this.setState({ picture: reader.result }); 
    } 
  } 
  reader.readAsDataURL(e.target.files[0]) 
}

// 提交表单时发送数据
createPost() { 
  const data = new FormData(); 
  data.append('file', this.state.picture); 
  axios.post('/api/createPost', data).then((res) => console.log(res)); 
}

后端 Express + Multer 代码

const storage = multer.diskStorage({ 
  destination: (req, file, cb) => { 
    cb(null, __dirname + `/i/posts/${uuid().split('-').join('')}/`) 
  }, 
  filename: (req, file, cb) => { 
    console.log(file); 
    cb(null, Date.now() + path.extname(file.originalname)) 
  } 
}) 
const upload = multer({ storage: storage });

// 上传路由
app.post('/api/createPost', upload.single('file'), (req, res) => { 
  console.log(req.file); // 始终输出 undefined
})

问题根源分析 #

一开始的核心错误很明显：我把 FileReader 生成的 base64 编码字符串传给了 FormData，而 Multer 只认原始的二进制 File 对象。Multer 是用来解析 multipart/form-data 格式的文件流的，base64 字符串对它来说只是普通文本，自然识别不了。

后来我改成把原始 File 对象存入状态（this.setState({ file: e.target.files[0] });），但问题依然存在，推测可能的额外原因：

• 前端请求手动设置了 Content-Type：Axios 处理 FormData 时会自动添加正确的 multipart/form-data 头部（带边界符），如果手动覆盖反而会导致 Multer 无法解析
• 后端存储目录不存在：Multer 的 diskStorage 不会自动创建目录，如果目标文件夹不存在，会导致上传失败（不过一般会抛错，而非返回 undefined）
• 依赖或版本冲突：比如未正确引入 path、uuid 这类工具库，或者 Multer 版本与 Express 不兼容

替代解决方案：改用 express-fileupload #

折腾半天没搞定 Multer，我换了 express-fileupload 组件，很快就成功了。以下是可行的完整实现：

后端配置（先安装依赖：npm install express-fileupload）

const fileUpload = require('express-fileupload');
const fs = require('fs');
const { v4: uuid } = require('uuid');

// 注册文件上传中间件
app.use(fileUpload());

app.post('/api/createPost', (req, res) => { 
  // 检查是否有文件上传
  if (!req.files || Object.keys(req.files).length === 0) { 
    return res.status(400).send('No files were uploaded.'); 
  } 
  
  const file = req.files.file; 
  // 生成唯一的上传目录（自动创建不存在的父目录）
  const uploadDir = __dirname + `/i/posts/${uuid().split('-').join('')}/`;
  fs.mkdirSync(uploadDir, { recursive: true });
  
  // 构建带时间戳的文件名，避免重名
  const fileExt = file.name.split('.').pop();
  const uploadPath = `${uploadDir}${Date.now()}.${fileExt}`; 
  
  // 提取用于数据库存储的相对路径
  const uploadPathArray = uploadPath.split('/');
  const imageURL = `/${uploadPathArray.slice(Math.max(uploadPathArray.length - 2)).join('/')}`;
  
  // 保存文件到服务器
  file.mv(uploadPath, function(err) { 
    if (err) return res.status(500).send(err); 
    // 这里可以把 imageURL 等信息存入数据库
    res.status(200).json({ message: '上传成功', imageURL });
  });
});

前端修改（保留预览，同时传递原始 File）

uploadImage = (e) => { 
  const file = e.target.files[0];
  // 依然用 FileReader 实现预览
  const reader = new FileReader(); 
  reader.onload = (e) => { 
    if (reader.readyState === 2) { 
      this.setState({ picturePreview: reader.result }); 
    } 
  } 
  reader.readAsDataURL(file);
  // 保存原始文件对象用于上传
  this.setState({ file }); 
}

createPost() { 
  const data = new FormData(); 
  data.append('file', this.state.file); 
  axios.post('/api/createPost', data)
    .then((res) => console.log('上传成功', res))
    .catch(err => console.error('上传失败', err));
}

总结 #

如果遇到 Multer 无法解析文件的问题，优先检查这几点：

• 是否传递的是原始 File 对象，而非 base64 或其他格式的字符串
• 前端请求不要手动设置 Content-Type（Axios 处理 FormData 会自动搞定）
• 确保后端存储目录已存在，或者开启自动创建

如果还是搞不定，express-fileupload 是个不错的替代方案，配置更简洁，上手成本低。

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