FormData是HTML5原生上传带参数最可靠方式，天然支持文件与字段混合提交，自动设置正确multipart/form-data头，服务端无需额外解析；手动拼接URL、JSON或设Content-Type均会导致失败。
用 FormData 附加参数最可靠
HTML5 原生上传带参数，FormData 是唯一推荐方式。它天然支持文件 + 字段混合提交，且能被 XMLHttpRequest 和 fetch 正确识别为 multipart/form-data，服务端无需额外解析逻辑。
常见错误是手动拼接 URL 参数或 JSON 字符串传给 fetch，这会导致文件无法上传（Content-Type 不匹配）或后端收不到文件字段。
- 必须先创建
FormData实例，再用append()添加文件和普通字段 - 文件字段名要和服务端约定一致（如
avatar、file） - 普通字段（如
user_id、category）也用append()加入，不要试图塞进body对象里
const form = document.querySelector('#upload-form');
form.addEventListener('submit', async (e) => {
e.preventDefault();
const formData = new FormData();
const fileInput = document.querySelector('#file');
const file = fileInput.files[0];
if (file) {
formData.append('file', file); // 文件字段
}
formData.append('user_id', '123'); // 普通参数
formData.append('type', 'avatar');
const res = await fetch('/api/upload', {
method: 'POST',
body: formData // 直接传 formData，不设 headers
});
});
fetch 不能手动设置 Content-Type
一旦使用 FormData 作为 body，浏览器会自动设置正确的 Content-Type（含随机 boundary）。若手动加 headers: {'Content-Type': 'multipart/form-data'}，反而会破坏协议，导致后端解析失败，常见报错如 Invalid boundary in multipart 或直接收不到文件。
- 完全不要在
fetch中设置Content-Type头 - 也不要用
JSON.stringify()包裹FormData—— 这会让整个对象变成字符串，文件二进制数据丢失 - 如果需携带认证 token，应放在
Authorization头里，不影响 multipart
兼容性与大文件处理注意点
FormData 在 IE10+、所有现代浏览器中均支持，但 IE10/11 不支持 fetch，需回退到 XMLHttpRequest；另外，大文件上传时，FormData.append() 本身无大小限制，但实际受浏览器内存和服务器配置约束。
立即学习“前端免费学习笔记（深入）”；
- 上传前建议校验
file.size，避免前端卡顿或触发服务端 413 错误 - 如需进度提示，
XMLHttpRequest.upload.onprogress可用，fetch原生不支持，需用ReadableStream+TransformStream手动拆包（复杂度高，非必要不推荐） - Node.js 后端（如 Express）需配合
multer，PHP 用$_FILES，Python Flask 用request.files，字段名必须和formData.append()的第一个参数严格一致
不用 FormData 的替代方案风险高
有人尝试用 base64 编码文件再和参数一起 JSON 提交，或用 Blob + 自定义 Content-Type，这些做法都绕过了标准 multipart 流程：
- base64 会使体积膨胀约 33%，上传变慢，服务端解码增加 CPU 开销
- 手动构造 multipart body 容易出错（boundary 格式、换行符、编码），不同浏览器行为不一致
- 移动端 WebView（尤其旧版 Android）对非标准 multipart 支持更差，容易静默失败
真正需要自定义协议的场景极少，绝大多数业务用 FormData 就够了。参数多、嵌套深？那就用多个 append()，比如 formData.append('meta[author]', 'Alice')，后端框架通常能自动解析这种命名格式。
