如何在前端使用 FormData 正确上传用户头像并更新资料-html教程

本文详解为何直接 json 发送文件字段失败，以及如何通过 formdata 构建 multipart/form-data 请求，配合 multer 中间件实现头像、姓名、邮箱的完整更新。

在 Web 应用中，更新用户资料（如姓名、邮箱）通常使用 application/json 请求体即可，但文件上传必须使用 multipart/form-data 编码格式——这是 HTTP 协议规范决定的底层限制。你遇到的“图像不更新，而姓名和邮箱正常”问题，根本原因在于：前端错误地将 File 对象序列化进了 JSON.stringify()，导致后端 multer 完全收不到文件字段。

❌ 错误做法：JSON 封装文件（无效）

// ⚠️ 错误！File 对象无法被 JSON 序列化，会变成 {} 或 null
body: JSON.stringify({ name, email, image })
headers: { 'Content-Type': 'application/json' }

此时 req.file 永远为 undefined，后端逻辑跳过图片处理，仅更新了 name 和 email。

✅ 正确做法：使用 FormData 构建表单数据

FormData 是浏览器原生 API，专为构造 multipart/form-data 请求设计，能自动处理文件二进制流与文本字段混合提交：

const userDataForm = document.querySelector('.profile-update');

if (userDataForm) {
  userDataForm.addEventListener('submit', async (e) => {
    e.preventDefault();

    const form = new FormData();
    form.append('name', document.getElementById('nameInput').value);
    form.append('email', document.getElementById('emailInput').value);

    const fileInput = document.getElementById('profile-img-file-input');
    if (fileInput.files.length > 0) {
      form.append('photo', fileInput.files[0]); // 字段名 'photo' 必须与 multer.upload.single('photo') 一致
    }

    try {
      const res = await fetch('/api/v1/users/updateMe', {
        method: 'PATCH',
        body: form // ✅ 不设 headers！浏览器自动设置 Content-Type 并附带 boundary
      });

      const data = await res.json();
      if (data.status === 'success') {
        showAlert('success', 'Profile updated successfully');
        window.location.reload(); // 刷新页面以显示新头像
      }
    } catch (err) {
      console.error(err);
      alert('Update failed: ' + err.message);
    }
  });
}

? 关键注意事项

• 字段名严格匹配：form.append(‘photo’, …) 中的 ‘photo’ 必须与后端 upload.single(‘photo’) 的参数完全一致，否则 Multer 不会捕获该文件。
• 禁止手动设置 Content-Type：当 body 是 FormData 时，切勿添加 headers: { ‘Content-Type’: ‘…’ } —— 浏览器会自动设置为 multipart/form-data; boundary=…，手动覆盖反而导致请求解析失败。
• 服务端路由顺序不可变：确保 uploadUserPhoto（Multer 中间件）在 updateMe 之前执行，否则 req.file 无法注入。
• 空文件容错：前端应检查 files[0] 是否存在，避免向后端发送 undefined 文件；后端 resizeUserPhoto 已有 if (!req.file) return next(); 防御，可安全跳过处理。
• EJS 图片路径更新：确保 ” alt=”如何在前端使用 FormData 正确上传用户头像并更新资料” > 中的 user.photo 是存储后的文件名（如 user-123-1715678901234.jpeg），且 public/assets/img/ 目录可被静态托管访问。

✅ 补充验证建议

在开发阶段，可在后端 updateMe 开头添加调试日志：