FormData 上传文件为什么不能手动设置 multipart 请求头

上传文件时，最容易踩的坑不是文件对象本身，而是手动写了 multipart/form-data。只要请求体交给 FormData，就应让浏览器自动生成请求头；否则请求头里的 boundary 可能缺失，或与实际请求体的分隔符不一致，服务端自然找不到文件。

为什么手动设置 Content-Type 会让上传失败

multipart 请求不是一段简单的二进制内容。浏览器会把普通字段和文件拆成多个 part，并在每个 part 之间写入一个 boundary。例如请求头通常会带有类似 boundary=----FormBoundary... 的参数，正文也必须使用同一个值分隔字段。如果代码只写了 multipart/form-data，却没有同步构造正文，服务端解析器就没有可靠的切分依据。

这也是“Network 面板里能看到 POST，但后端文件为空”的常见原因。问题不在于请求方法，而在于 Content-Type 参数和 body 的编码责任被拆开了。MDN 对 Fetch 和 XMLHttpRequest 都给出同一个提醒：使用 FormData 发送文件时，不要显式设置 Content-Type，让浏览器完成这一步。

正确写法是让浏览器接管 multipart 请求头

最小可用写法只配置 method 和 body。文件输入框需要一个稳定的 name，额外字段用 append 添加；不要为了“补全请求头”而增加 Content-Type。

const form = document.querySelector("#profile-form");

form.addEventListener("submit", async (event) => {
  event.preventDefault(); // 阻止浏览器重复提交原生表单
  const data = new FormData(form);
  data.append("source", "settings"); // 追加服务端需要的普通字段

  const response = await fetch("/api/profile/avatar", {
    method: "POST",
    body: data, // 让浏览器生成 Content-Type 和 boundary
  });

  if (!response.ok) {
    throw new Error(`上传失败：HTTP ${response.status}`); // HTTP 错误要单独处理
  }
  console.log("上传完成");
});

如果不使用 JavaScript，原生表单也可以声明 enctype="multipart/form-data" 后直接提交。使用 XMLHttpRequest 时同样只调用 send(data)，不要调用 setRequestHeader("Content-Type", ...)。如果需要自定义文件名，可以使用 data.append("avatar", file, "avatar.png")，这不会改变 boundary 的生成责任。

如何从请求头和表单字段定位上传问题

去掉手动请求头后，打开开发者工具的 Network 面板检查实际请求。请求头应能看到带 boundary 参数的 Content-Type；Payload 中应有文件字段和普通字段。若请求头正常但服务端仍说字段缺失，优先检查下面几项：

注意不要把 boundary 问题和文件大小限制混为一谈。若 Network 中请求体完整、服务端也成功解析出字段，但返回 413 或业务层拒绝，那是上传限制或业务校验；若浏览器直接被 CORS 拦截，则先解决跨域响应，不能靠修改 multipart 请求头绕过。

哪些变体可以安全使用，哪些写法不要混用

FormData 适合文件和普通字段混合提交；URLSearchParams 适合没有文件的键值表单；JSON body 则应配合 application/json。三者的编码方式不同，不能把 JSON 的请求头复制到 FormData，也不能因为使用了 fetch 就认为所有 body 都会自动变成 multipart。

一个实用判断是：body 是 FormData，就只负责准备字段和文件；body 是 JSON 字符串，才显式声明 JSON；body 是 URLSearchParams，可以声明表单编码。上传失败时按“请求头 boundary → 字段 name → 文件对象 → CORS 和服务端限制”的顺序检查，通常比反复更换请求库更快。

常见问题

FormData 里能不能手动加入 boundary？

不建议。boundary 属于整次 multipart 编码，应该由浏览器根据实际 body 统一生成。

为什么 FormData 没有收集某个输入框？

先检查控件是否有 name，以及它或所在 fieldset 是否被 disabled；没有 name 的字段不会进入表单数据。

axios 也需要手动设置 Content-Type 吗？

只要底层把 FormData 作为 body 交给浏览器，原则仍是不要手动覆盖 multipart 的 Content-Type；具体还要看封装层是否改写了请求头。

参考资料：MDN：Using FormData Objects；MDN：Using the Fetch API。