JavaScript原生文件上传:使用FormData与Fetch API实现基础提交

作者:木棉

时间:2026-11-20

浏览:207

深入讲解如何使用原生JavaScript的FormData与Fetch API实现基础文件上传提交,分析Multipart协议机制、Boundary自动生成原理及常见高频错误排查。

文章目录
在现代 Web 开发中,提交本地文件不需要借助 Axios 或第三方上传插件。仅依靠浏览器内置的 <input type="file"> 元素、FormData 构造器以及 Fetch API,即可完成符合标准 HTTP 规范的文件异步上传。实现此任务的核心逻辑包含三个关键环节:从用户交互中提取 File 对象、将文件载入 FormData 实例,以及使用 fetch 发送 POST 请求。最需要强调的原则是:绝对不要手动设置 Content-Type 请求头,交由浏览器自动计算边界才是上传成功的保障。
JavaScript原生文件上传:使用FormData与Fetch API实现基础提交
图 1:JavaScript 原生文件上传端到端数据流与各阶段核心职责

一、获取文件对象:从 DOM 到 File 实例

在浏览器环境中,出于安全沙箱机制的限制,JavaScript 无法直接访问操作系统文件系统的任意路径,必须由用户通过界面交互主动选取文件。HTML 中的 <input type="file"> 便是承载该交互的标准入口。

当用户选中文件后,该 <input> 元素的 files 属性会暴露一个只读的 FileList 伪数组对象。其中的每个成员都是一个 File 实例(继承自 Blob)。File 实例携带了文件的元数据:

  • name:文件名(如 avatar.png),不包含敏感的本地绝对路径。
  • size:文件大小,以字节(Byte)为单位。
  • type:文件的 MIME 类型(如 image/png 或 application/pdf),若系统无法推导则可能为空字符串。

以下是基础的 HTML 结构以及监听文件变动的核心代码:

<!-- HTML 界面结构 -->
<div class="upload-widget">
  <input type="file" id="fileInput" />
  <button type="button" id="uploadBtn">开始上传</button>
</div>

<script>
  const fileInput = document.getElementById('fileInput');
  const uploadBtn = document.getElementById('uploadBtn');

  // 当用户在弹窗中完成文件选取时触发
  fileInput.addEventListener('change', (event) => {
    const file = event.target.files[0];
    if (file) {
      console.log(`已就绪: ${file.name}, 体积: ${file.size} 字节, 类型: ${file.type}`);
    }
  });
</script>

在实际项目中,在提取 File 之后,通常需要先进行前端防御校验。例如限制文件最大体积为 5MB,或者验证扩展名是否符合预期,从而减少无效的网络传输开销。

二、装配表单数据:FormData 的用法与场景

常规的 JSON 请求(即 Content-Type: application/json)并不适合直接传输大型原始二进制字节流。若将二进制转为 Base64 字符串嵌入 JSON,不仅会带来约 33% 的体积膨胀,还会增加前端编解码的 CPU 负担。

现代标准的做法是使用 FormData 接口。FormData 能够在内存中构建一个专门用于网络提交的表单数据集,完美支持混合打包普通键值文本与二进制文件。

1. 单文件与元数据混合装配

const formData = new FormData();

// 挂载文件:第一个参数为后端字段名,第二个参数为 File 实例,第三个可选参数为自定义文件名
formData.append('document', file, file.name);

// 混入业务元数据(普通字符串参数)
formData.append('userId', '10086');
formData.append('category', 'invoices');

2. 多文件(Multiple Files)场景的装配

若 <input type="file" multiple> 启用了多选属性,可通过循环遍历 fileInput.files 集合,依次调用 append 将多个文件追加到同一个字段名下:

const multiFileInput = document.getElementById('multiFileInput');
const formData = new FormData();

for (let i = 0; i < multiFileInput.files.length; i++) {
  // 保持字段名一致(如 'files' 或根据后端框架要求命名为 'files[]')
  formData.append('files', multiFileInput.files[i]);
}

三、发起提交:Fetch API 与 Content-Type 陷阱

组装好 FormData 实例后,即可调用 window.fetch 发起网络请求。此处存在初学者最容易踩入的严重误区:试图在 headers 中手动指定 'Content-Type': 'multipart/form-data'。

JavaScript原生文件上传:使用FormData与Fetch API实现基础提交
图 2:HTTP Multipart 报文装配与 Content-Type 机制对比(不设 Header 与手动设头的差异)

为什么绝对不能手动设置 Content-Type?

在 HTTP 协议中,multipart/form-data 报文依靠一段随机且唯一的“分界标识符”(Boundary)来区分请求体中各个不同字段与二进制分块。例如:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryX7b9QE2...

这个 boundary 是浏览器底层网络引擎在真正发出请求时,实时随机生成并计算好的。如果我们在 fetch 配置项中手动写了 headers: { 'Content-Type': 'multipart/form-data' },浏览器就会完全遵照你的指定,导致发出的 HTTP 标头中缺失了 boundary 参数。

服务端接收到此请求后,由于拿不到 boundary 分界线,无法从字节流中切分出文件数据,最终抛出诸如 MultipartException: no multipart boundary was found 或 400 Bad Request 错误。

关键结论:只要将 FormData 实例直接赋值给 fetch 配置的 body 属性,且不在 headers 中指定 Content-Type,现代浏览器就会自动添加正确的 multipart/form-data 标头并自动补齐唯一的 boundary。
JavaScript原生文件上传:使用FormData与Fetch API实现基础提交
图 3:原生 JavaScript 文件上传标准操作四步执行流程

四、完整端到端实现:包含状态与错误处理

下面给出一份可直接运行的原生 JavaScript 文件上传函数实现,整合了 DOM 提取、体积拦截、Fetch 提交及针对 HTTP 状态码的健全处理:

/**
 * 原生文件提交实现函数
 * @param {HTMLInputElement} inputElement 文件输入框元素
 * @param {string} uploadUrl 服务端接收接口地址
 */
async function uploadFile(inputElement, uploadUrl) {
  const files = inputElement.files;
  if (!files || files.length === 0) {
    alert('请选择要上传的文件!');
    return;
  }

  const file = files[0];

  // 1. 前端体积预检(例如限制 10MB)
  const MAX_SIZE = 10 * 1024 * 1024;
  if (file.size > MAX_SIZE) {
    alert('文件体积不能超过 10MB!');
    return;
  }

  // 2. 组装 FormData
  const formData = new FormData();
  formData.append('file', file, file.name);
  formData.append('uploadTime', Date.now().toString());

  try {
    // 3. 发送 Fetch 请求(不配置 Content-Type)
    const response = await fetch(uploadUrl, {
      method: 'POST',
      body: formData,
      // 如有鉴权需求可附加 Authorization,但切勿设置 Content-Type
      headers: {
        // 'Authorization': 'Bearer ' + token
      }
    });

    // 4. 显式校验 HTTP 响应状态
    if (!response.ok) {
      throw new Error(`服务器响应错误: HTTP ${response.status} ${response.statusText}`);
    }

    const result = await response.json();
    console.log('上传成功,服务端返回:', result);
    alert('文件上传成功!');

    // 5. 交互状态复位:清空 input 控件的值
    inputElement.value = '';

  } catch (error) {
    console.error('上传过程发生异常:', error);
    alert(`上传失败: ${error.message}`);
  }
}

// 绑定触发逻辑
document.getElementById('uploadBtn').addEventListener('click', () => {
  const input = document.getElementById('fileInput');
  uploadFile(input, '/api/upload');
});

五、关键边界与高频问题排查

在实现原生文件上传时,除了上述关于 Content-Type 的规避原则外,还有两个极其普遍的工程边界问题需要处理。

JavaScript原生文件上传:使用FormData与Fetch API实现基础提交
图 4:原生文件上传常见故障与排查诊断矩阵

1. 同一文件无法再次触发 change 事件

用户上传了 demo.pdf 之后,如果发现内容需要修改并删除了当前界面的预览,随后在弹窗中再次选择名为 demo.pdf 的文件,此时 <input> 上的 change 事件往往不会触发。

这是因为浏览器的 change 事件依赖控件的 value 属性是否发生改动。连续两次选中同一绝对路径的文件,input.value 保持不变。解决方法是在上传结束或取消时,显式执行 input.value = '' 清空内部状态。

2. Fetch 的“不主动报错”特性

很多开发者容易混淆 fetch 与 Axios 的异常处理模型。fetch 返回的 Promise 只有在遭遇网络断开、DNS 解析失败或跨域被阻断等致命网络错误时才会进入 reject 状态。

如果服务器返回了 400 Bad Request、403 Forbidden 甚至 500 Internal Server Error,fetch 依然会正常 resolve。因此,必须在拿到 response 后首先判断 response.ok,当其为 false 时主动 throw new Error(),以确保代码进入统一的错误流。

3. 使用 AbortController 实现超时与手动取消

大文件传输可能遭遇较长时间的网络阻塞。Fetch API 原生支持与 AbortController 协同工作,为上传任务提供超时熔断与手动中断能力:

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000); // 30秒超时

try {
  const response = await fetch('/api/upload', {
    method: 'POST',
    body: formData,
    signal: controller.signal
  });
  clearTimeout(timeoutId);
  // 后续响应处理...
} catch (err) {
  if (err.name === 'AbortError') {
    console.warn('请求已超时或被用户主动取消');
  } else {
    console.error('网络或其它异常:', err);
  }
}

六、技术全景复盘与最佳实践

原生文件上传虽然精简,但涵盖了浏览器底层抽象、网络协议及异步交互的完整闭环。将这套知识融会贯通,是理解复杂上传组件(如大文件分片、断点续传等)的坚实基石。

JavaScript原生文件上传:使用FormData与Fetch API实现基础提交
图 5:JavaScript 原生文件上传核心技术栈全景复盘

在生产环境中使用 FormData 与 Fetch 实现原生上传时,建议遵循以下简明规则:

  1. 防御先行:在文件提交前,基于 File.size 和 File.type 校验体积与格式,杜绝无效流量。
  2. 信任标准:实例化 FormData 承载数据,把请求头交还给浏览器,避免一切手工指定 Content-Type 的多余操作。
  3. 健全响应:在解包响应前严格核对 response.ok,配合 try...catch 将网络错误与业务状态码统一处理。
  4. 闭环复位:上传结束后及时重置 input.value,并在请求期间对提交按钮执行 disabled 处理,杜绝重复连击。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章