React项目multipart/form-data表单图片无法上传问题求助

核心原因 #

直接将表单数据序列化为JSON提交会丢失File对象——JSON无法处理Blob/File类型，必须使用FormData对象封装multipart/form-data格式的数据。

具体实现步骤 #

1. 正确收集文件数据 #

在文件选择的onChange事件中，存储File对象而非假路径：

// 状态管理
const [selectedFile, setSelectedFile] = useState(null);

// 文件选择事件处理
const handleFileChange = (e) => {
  // 取第一个选中的文件
  setSelectedFile(e.target.files[0]);
};

// 表单中的文件输入组件
<input 
  type="file" 
  name="avatar" // 需与后端multer配置的字段名完全一致
  onChange={handleFileChange}
  accept="image/*"
/>

2. 用FormData封装所有表单数据 #

提交时创建FormData实例，将当前步骤及之前步骤的所有表单字段（包括文件）追加进去：

const handleStep2Submit = async () => {
  const formData = new FormData();
  
  // 添加之前步骤收集的普通字段（比如姓名、部门）
  formData.append('employeeName', employeeName);
  formData.append('department', department);
  
  // 添加图片文件，第三个参数可选，用于指定文件名
  if (selectedFile) {
    formData.append('avatar', selectedFile, selectedFile.name);
  }

  // 发送请求（Axios示例）
  try {
    await axios.post('/api/employees/add', formData, {
      // 禁止手动设置Content-Type！Axios会自动添加带boundary的正确请求头
      // headers: { 'Content-Type': 'multipart/form-data' } // 这行必须删掉
    });
    
    // 提交成功逻辑，比如跳转步骤或提示成功
  } catch (error) {
    console.error('提交失败:', error);
  }
};

3. Fetch API写法（若不使用Axios） #

const handleStep2Submit = async () => {
  const formData = new FormData();
  formData.append('employeeName', employeeName);
  formData.append('department', department);
  if (selectedFile) {
    formData.append('avatar', selectedFile);
  }

  const response = await fetch('/api/employees/add', {
    method: 'POST',
    body: formData,
    // 同样禁止手动设置Content-Type，浏览器会自动处理
  });

  if (response.ok) {
    // 成功逻辑
  } else {
    const errorText = await response.text();
    console.error('提交失败:', errorText);
  }
};

常见坑点避免 #

• 禁止手动设置Content-Type：手动设置会缺失浏览器自动生成的boundary分隔符，导致后端无法解析数据。
• 不要序列化FormData：切勿使用JSON.stringify(formData)，这会将FormData转为空对象{}，丢失所有数据。
• 字段名一致性：确保input的name属性与后端multer配置完全匹配（比如后端用upload.single('avatar')，则name必须为avatar）。
• 分步骤字段整合：分步骤提交时，要把之前步骤的所有字段都加到FormData里，不能只传当前步骤的图片。

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