FormData实战指南：文件上传与表单处理的高效方案

又踩坑了，FormData 上传文件居然没带上字段

上周做后台表单提交，带文件上传那种，前端用 FormData 拼数据发给后端。结果后端同事一脸懵：“文件收到了，但其他字段全空。” 我当时就纳闷了，明明每个字段都 append 进去了啊？折腾了大半天，最后发现是个低级错误，但过程真够绕的。

一开始我以为是 append 写错了

我第一反应就是检查代码是不是漏写了字段名或者值。比如：

const formData = new FormData();
formData.append('title', document.getElementById('title').value);
formData.append('cover', fileInput.files[0]);

看起来没问题对吧？但后端就是收不到 title。我还特意在浏览器 DevTools 里打印出来看：

for (let [key, value] of formData.entries()) {
  console.log(key, value);
}

控制台确实输出了 title xxx 和 cover [File]，说明数据在前端是有的。那问题出在哪？

后来试了下发现：Content-Type 别手动设！

我翻了下之前的老项目，发现有个地方手动设置了请求头：

fetch('/api/upload', {
  method: 'POST',
  headers: {
    'Content-Type': 'multipart/form-data'
  },
  body: formData
})

看到这儿我一拍大腿——这里我踩了个大坑！FormData 的正确用法是不要手动设置 Content-Type。因为 multipart/form-data 需要一个 boundary（边界字符串），这个 boundary 是浏览器自动生成的，如果你手动写了 Content-Type，但没带 boundary，服务器根本解析不了。

正确的做法是：让浏览器自动设置 Content-Type，它会带上正确的 boundary。所以应该这么写：

fetch('https://jztheme.com/api/upload', {
  method: 'POST',
  // 注意：headers 不要包含 Content-Type
  body: formData
})

就这么一行删掉，后端立马能收到所有字段了。真是哭笑不得，这种细节文档其实写了，但谁没事去看规范啊，都是凭经验写，结果栽在这儿。

还有个隐藏坑：字段值不能是 null 或 undefined

解决了 Content-Type 问题后，又遇到另一个诡异情况：有时候字段还是空的。排查发现，如果用户没填某个输入框，.value 可能是空字符串，这没问题；但如果我从 Vuex 或状态管理里取值，不小心传了 undefined，FormData.append('foo', undefined) 实际上会变成字符串 "undefined" 发出去！后端收到的就是字面量 “undefined”，而不是空值。

更糟的是，如果传 null，也会变成字符串 "null"。这显然不是我们想要的。

所以现在我养成了习惯：append 之前先做个兜底处理：

const safeValue = value ?? '';
formData.append('description', safeValue);

或者更严格点，只 append 有实际内容的字段：

if (value !== null && value !== undefined && value !== '') {
  formData.append('optionalField', value);
}

不过要注意，有些字段即使为空字符串也需要传（比如清空某个设置），这时候就不能省略，得明确传 ''。

核心代码就这几行

现在我把整个封装逻辑整理了一下，亲测有效，贴出来供参考：

function createFormDataFromForm(formElement) {
  const formData = new FormData();
  
  // 先把表单里所有原生字段加进去（包括文件）
  const nativeEntries = new FormData(formElement);
  for (let [key, value] of nativeEntries.entries()) {
    // 过滤掉空的非文件字段（可选）
    if (value instanceof File || value !== '') {
      formData.append(key, value);
    }
  }

  // 手动追加额外字段（比如 token、meta 信息等）
  const extraFields = {
    userId: localStorage.getItem('userId'),
    timestamp: Date.now()
  };

  for (const [key, value] of Object.entries(extraFields)) {
    if (value != null) {
      formData.append(key, String(value));
    }
  }

  return formData;
}

// 使用示例
const form = document.getElementById('uploadForm');
const formData = createFormDataFromForm(form);

fetch('https://jztheme.com/api/upload', {
  method: 'POST',
  body: formData
})
.then(res => res.json())
.then(data => console.log('上传成功', data))
.catch(err => console.error('上传失败', err));

这段代码的好处是：既利用了 new FormData(form) 自动收集表单的能力，又能灵活追加非表单字段，还做了空值处理。而且完全不用管 Content-Type。

顺便聊聊 FormData 的几个冷知识

其实在这次排查过程中，我还顺手查了几个 FormData 的细节：

• FormData 的键可以重复！也就是说你可以 append('tag', 'js') 然后再 append('tag', 'react')，后端收到的就是数组形式的 tag。这点和普通对象不一样。
• 如果你用 set() 而不是 append()，会覆盖同名字段。所以批量添加时一定要用 append。
• 在 Safari 早期版本中，FormData 不支持直接遍历（没有 entries() 方法），但现在基本不用考虑兼容性了。

另外，如果你用 Axios，它内部也会自动处理 FormData 的 Content-Type，所以同样不要手动设 header。但如果你用的是老式 XMLHttpRequest，也是一样的道理——别碰 Content-Type。

改完后还有个小瑕疵，但无大碍

现在功能是正常了，不过我发现如果用户快速连续提交，可能会触发多次请求。这不是 FormData 的问题，而是业务逻辑没做防重。我临时加了个按钮 loading 状态，但更彻底的做法应该是加请求去重或取消机制。不过这个需求优先级不高，先这样跑着吧，反正不影响主流程。

以上是我踩坑后的总结，如果你有更好的方案欢迎评论区交流。说实话，这种“看似简单实则暗坑”的问题最磨人，但解决后特别有成就感。下次再遇到类似问题，我肯定第一时间检查 Content-Type 有没有手贱加上去（笑）。