React使用axios.post向Express上传文件失败问题排查

前端（React + Axios）正确实现 #

上传包含文件的多值数据，必须用FormData——普通JSON无法处理二进制文件，直接传File对象只会序列化出path这类元数据，后端自然拿不到完整文件。

正确构建请求的示例代码：

// 假设你有获取到的File对象file，以及其他数据对象info
const formData = new FormData();

// 追加PDF文件，第三个参数是文件名（可选，不传则用File对象的name）
formData.append('pdfFile', file, file.name);

// 处理其他数据：如果是简单键值对，逐个追加
// 比如info = { title: "文档标题", author: "Nova" }
Object.entries(info).forEach(([key, value]) => {
  formData.append(key, value);
});

// 如果是复杂嵌套对象，先转成JSON字符串再追加
// formData.append('info', JSON.stringify(info));

// 发送请求：不要手动设置Content-Type为multipart/form-data
// 浏览器会自动生成带boundary的正确请求头，手动设置反而可能导致解析失败
axios.post('/api/upload', formData)
  .then(res => console.log('上传成功', res.data))
  .catch(err => console.error('上传失败', err));

可以通过console.log([...formData.entries()])查看FormData的所有内容，确认文件和数据都已正确追加。

后端（Express）配置要点 #

Express默认无法解析multipart/form-data类型的请求，必须用multer中间件处理文件上传。

1. 安装依赖：

npm install multer

2. 正确配置路由的示例：

const express = require('express');
const multer = require('multer');
const app = express();

// 配置文件存储路径（确保uploads文件夹已创建，否则会报错）
const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, './uploads');
  },
  filename: (req, file, cb) => {
    cb(null, file.originalname); // 保留原文件名，也可自定义命名规则
  }
});

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

// 接口路由：upload.single('pdfFile')对应前端FormData里的文件key
app.post('/api/upload', upload.single('pdfFile'), (req, res) => {
  // req.file 就是上传的PDF文件对象，包含path、originalname、size等信息
  console.log('收到文件:', req.file);
  
  // req.body 是其他表单数据
  // 如果前端传的是JSON字符串格式的info，需要解析：
  // const info = JSON.parse(req.body.info);
  console.log('收到其他数据:', req.body);
  
  res.status(200).json({ message: '上传完成' });
});

app.listen(3001, () => console.log('后端服务运行在3001端口'));

常见问题排查 #

• 后端拿不到文件：检查multer的single()参数是否和前端FormData的文件key完全一致；确认uploads文件夹存在；查看请求头是否为multipart/form-data; boundary=xxx（不是则说明前端没正确传FormData）。
• 后端拿到的info是[object Object]：这是因为直接把对象塞进FormData会被转成字符串，解决办法是要么逐个追加对象的字段，要么把对象转成JSON字符串再追加，后端再解析。
• 前端发送请求报错：检查后端是否跨域（可在Express加cors中间件），或者文件大小是否超过multer的默认限制（可通过multer({ limits: { fileSize: 10 * 1024 * 1024 } })调整）。

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