FormData 是浏览器专为表单提交（尤其含文件）设计的二进制容器，能自动处理 boundary、编码和 multipart 格式；直接传 JS 对象会导致文件二进制数据丢失，必须用 FormData.append() 添加文件或字段，fetch 会自动设置正确 Content-Type。
FormData 是什么，为什么不能直接传对象
浏览器原生 XMLHttpRequest 或 fetch 无法直接把普通 JS 对象（比如 {file: fileInput.files[0], name: "test"}）发给后端做文件上传。服务端收到的只是字符串化的键值对，文件二进制数据会丢失。必须用 FormData —— 它是浏览器专为表单提交（尤其是含文件）设计的二进制容器，能自动处理边界（boundary）、编码和 multipart 格式。
常见错误：手动把 File 对象 JSON.stringify 后塞进 body，结果后端收不到文件字段，只看到一串乱码或空值。
-
FormData实例可直接作为fetch的body，无需设Content-Type头（浏览器会自动设置并带上正确的boundary） - 不能用
JSON.stringify包裹FormData，否则它就变成字符串，失去二进制能力 - 添加字段时，
append()第二个参数如果是File或Blob，浏览器会自动提取文件名；如果只是字符串，就当普通文本字段
用 fetch + FormData 上传单个文件的最小可行代码
这是最常遇到的场景：用户选一个文件，点击上传按钮，前端把文件连同额外参数（如 id、type）一起发给接口。
const uploadFile = async (file, extraData = {}) => {
const formData = new FormData();
formData.append('file', file); // 必须是 File 对象，不是 fileInput.files[0].name
Object.keys(extraData).forEach(key => {
formData.append(key, extraData[key]);
});
try {
const res = await fetch('/api/upload', {
method: 'POST',
body: formData // 直接传，不要加 headers: {'Content-Type': 'multipart/form-data'}
});
return await res.json();
} catch (err) {
console.error('上传失败:', err);
}
};
// 调用示例
document.getElementById('fileInput').addEventListener('change', e => {
if (e.target.files.length > 0) {
uploadFile(e.target.files[0], { type: 'avatar', userId: '123' });
}
});
注意：fetch 内部会自动设置 Content-Type 为 multipart/form-data; boundary=xxxx，手动覆盖会导致后端解析失败。
立即学习“Java免费学习笔记（深入）”；
上传多个文件时 append 的写法差异
后端是否支持数组字段（如 files[]）取决于框架。Node.js 的 multer、PHP 的 $_FILES 默认把同名多文件当作数组，但需要前端统一字段名。
- 如果后端接收字段叫
files，且期望是数组：所有文件都用formData.append('files', file)（相同 key） - 如果后端按索引接收（如
files[0],files[1]）：需手动拼 key，如formData.append(`files[${i}]`, file) - 混合上传（多个文件 + 文本字段）完全没问题，
FormData支持任意顺序append
错误做法：试图用 formData.append('files', [file1, file2]) —— 这只会把数组转成字符串 "[object File],[object File]"，后端收不到真实文件。
监听上传进度时为什么 onprogress 只在 XMLHttpRequest 里有效
fetch 没有原生上传进度事件，只能靠 XMLHttpRequest 的 upload.onprogress。如果你需要显示「上传中 65%」，就得切回 XMLHttpRequest。
const xhrUpload = (file, extraData) => {
const formData = new FormData();
formData.append('file', file);
Object.entries(extraData).forEach(([k, v]) => formData.append(k, v));
return new Promise((resolve, reject) => {
const xhr = new XMLHttpRequest();
xhr.upload.onprogress = e => {
if (e.lengthComputable) {
const percent = (e.loaded / e.total) * 100;
console.log(上传进度: ${percent.toFixed(1)}%);
}
};
xhr.onload = () => resolve(xhr.response);
xhr.onerror = reject;
xhr.open('POST', '/api/upload');
xhr.send(formData);
});
};
关键点：xhr.upload 是上传专用事件对象，xhr.onprogress 是下载进度，别混淆。另外，XMLHttpRequest 不支持 async/await 直接等待，必须包装成 Promise。
真正容易被忽略的是：某些 CDN 或代理（如 Nginx）默认限制单次请求体大小，即使前端没报错，后端也可能收不到完整文件——这时要检查服务端配置（如 Nginx 的 client_max_body_size），而不是反复改前端代码。
