原生JS使用Fetch和FormData实现图片上传

作者:木棉

时间:2026-11-18

浏览:470

本文详细讲解如何使用原生 JavaScript 结合 Fetch API 与 FormData 对象实现图片上传功能,涵盖客户端文件选择、本地预览、格式与体积校验、FormData 组装、Fetch 请求配置及常见避坑实践。

文章目录

一、核心上传流程与基础实现

在浏览器中,本地磁盘上的图片无法通过常规 JSON 字符串的形式直接传给服务器(除非额外进行 Base64 编码,但这会导致体积膨胀约 33% 且增加编解码 CPU 损耗)。标准的做法是利用浏览器的 FormData 接口构建表单数据集,利用 multipart/form-data 编码方式将二进制流原样传输。

整个处理链路依次经历:DOM 事件捕获、本地属性校验与预览、构造 FormData 载荷、发起 Fetch 异步请求、处理服务端响应等阶段。

原生JS使用Fetch和FormData实现图片上传
图 1:原生 JS 图片上传端到端操作步骤与调用时序

我们先看一个最简且完整的端到端 HTML 与 JS 骨架结构:

<!-- 基础上传控件 -->
<div class="upload-box">
  <input type="file" id="imageInput" accept="image/png, image/jpeg, image/webp" />
  <button id="uploadBtn" disabled>确认上传</button>
  <div id="previewArea"></div>
</div>

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

  // 1. 监听文件选择
  imageInput.addEventListener('change', () => {
    const file = imageInput.files[0];
    if (file) {
      uploadBtn.disabled = false;
    } else {
      uploadBtn.disabled = true;
    }
  });

  // 2. 发起上传请求
  uploadBtn.addEventListener('click', async () => {
    const file = imageInput.files[0];
    if (!file) return;

    // 组装表单数据
    const formData = new FormData();
    formData.append('avatar', file, file.name);

    try {
      uploadBtn.disabled = true;
      uploadBtn.textContent = '上传中...';

      const response = await fetch('/api/upload', {
        method: 'POST',
        body: formData
        // 注意:此处绝不能手动设置 Content-Type 请求头
      });

      if (!response.ok) {
        throw new Error(`HTTP 异常,状态码: ${response.status}`);
      }

      const result = await response.json();
      console.log('上传成功,服务器返回:', result);
      alert('上传成功!图片URL: ' + result.url);
    } catch (error) {
      console.error('上传失败:', error);
      alert('上传失败,请重试');
    } finally {
      uploadBtn.disabled = false;
      uploadBtn.textContent = '确认上传';
    }
  });
</script>

二、深入 FormData 与关键请求头陷阱

在实现图片上传时,初学者最容易踩中的一个深坑是:手动在 Fetch 的 headers 中添加 'Content-Type': 'multipart/form-data'。这种做法必然会导致服务端报 400(Bad Request)或 500 解析失败。

为什么手动设置反而会报错?原因在于 multipart/form-data 报文格式的特殊性。HTTP 协议要求在多段表单数据中,每一段数据之间必须用一个随机生成的唯一边界字符串(Boundary)来进行隔离。

原生JS使用Fetch和FormData实现图片上传
图 2:HTTP multipart 报文解剖与浏览器自动 Boundary 计算对比

如图 2 所示,当开发者将一个 FormData 实例直接传给 fetch 的 body 并且不指定任何 Content-Type 时,浏览器会在发送底层网络包前自动完成以下两件事:

  1. 随机生成一段全局唯一的边界分隔符,例如 ----WebKitFormBoundary7MA4YWxkTrZu0gW。
  2. 自动注入完整的 Content-Type 请求头:multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW。

如果开发者手动写了 headers: { 'Content-Type': 'multipart/form-data' },则会将原本包含 boundary 参数的完整请求头粗暴覆盖成只有 multipart/form-data 的残缺头。后端的接收中间件(如 Node.js 的 multer、Java 的 CommonsMultipartResolver、Python 的 Django/FastAPI)在读取到该请求时,因找不到 boundary 分隔符,便无法对二进制数据流与表单字段进行切分,直接抛出异常。

重要规则:FormData 与 Fetch 请求头原则

当请求体为 FormData 时,绝不要手动设置 Content-Type。但如果有身份鉴权(如 JWT Token)或特定业务头,完全可以正常传入自定义字段,例如:

fetch('/api/upload', {
  method: 'POST',
  headers: {
    // 携带认证信息是允许的
    'Authorization': 'Bearer ' + userToken
    // 严禁在此处显式写 'Content-Type'
  },
  body: formData
});

三、生产级客户端校验与本地即时预览

实际项目开发中,图片上传必须具备严密的前端防御措施:不能等到几个兆的二进制流全部传到服务器后,才由后端告知“文件格式不符”或“超出尺寸限制”。良好的交互应在用户选中文件的毫秒级时间内,在前端完成格式校验、体积判断与本地图片预览。

1. 文件类型与体积的双重把关

虽然 <input type="file" accept="image/*"> 可以在系统文件选择框中过滤大部分非图片文件,但用户仍可以通过选择“所有文件 (*.*)”强行选中非法格式。因此必须通过 JS 读取 file.type 与 file.size 实施拦截。

function validateImage(file) {
  // 1. 允许的文件类型列表
  const validTypes = ['image/jpeg', 'image/png', 'image/webp', 'image/gif'];
  if (!validTypes.includes(file.type)) {
    alert('仅支持上传 JPG、PNG、WebP 或 GIF 格式的图片!');
    return false;
  }

  // 2. 限制文件大小不超过 5MB (1MB = 1024 * 1024 字节)
  const maxSize = 5 * 1024 * 1024;
  if (file.size > maxSize) {
    alert('图片大小不能超过 5MB!当前体积:' + (file.size / 1024 / 1024).toFixed(2) + 'MB');
    return false;
  }

  return true;
}

2. 本地即时预览:URL.createObjectURL 的优势

在上传大图时,用户希望在点击“提交”前确认选中的图片内容。前端生成本地预览常见有两种方案:FileReader.readAsDataURL() 与 URL.createObjectURL()。

方案 实现机制 性能与内存开销 推荐场景
URL.createObjectURL(file) 创建指向内存中文件二进制数据的 blob: URI 引用 同步执行,开销极小,不占用大量字符串内存 首选推荐:纯界面即时预览、本地渲染
FileReader.readAsDataURL(file) 异步将文件全部转码为 Base64 文本 耗费 CPU 算力进行 Base64 编码,内存占用暴增 33% 需要直接持久化 Base64 字符串到数据库等特殊场景

使用 URL.createObjectURL 时必须牢记:该 URL 存活于当前页面的 document 生命周期内。若不主动释放,频繁选图会导致内存占用持续上涨。在图片上传成功或被用户替换后,应调用 URL.revokeObjectURL(previewUrl) 归还内存。

原生JS使用Fetch和FormData实现图片上传
图 3:客户端状态机生命周期与分层异常防御流转图

四、生产级完整代码与服务端协同

结合前述的状态管理、校验、本地预览、请求超时取消与资源清理,以下提供一套完备的、可直接用于工业级生产的前端上传组件实现代码。

/**
 * 原生 JS 图片上传综合实现
 */
class ImageUploader {
  constructor(options) {
    this.fileInput = document.querySelector(options.fileInputSelector);
    this.uploadBtn = document.querySelector(options.uploadBtnSelector);
    this.previewImg = document.querySelector(options.previewImgSelector);
    this.statusText = document.querySelector(options.statusTextSelector);
    this.uploadUrl = options.uploadUrl;
    this.maxSizeBytes = (options.maxSizeMB || 5) * 1024 * 1024;
    this.currentBlobUrl = null;
    this.abortController = null;

    this.initEvents();
  }

  initEvents() {
    this.fileInput.addEventListener('change', (e) => this.handleFileChange(e));
    this.uploadBtn.addEventListener('click', () => this.upload());
  }

  handleFileChange(e) {
    const file = e.target.files[0];
    if (!file) return;

    // 格式校验
    if (!file.type.startsWith('image/')) {
      alert('请选择有效的图片文件!');
      this.resetInput();
      return;
    }

    // 大小校验
    if (file.size > this.maxSizeBytes) {
      alert('图片大小超出限制(最高 ' + (this.maxSizeBytes / 1024 / 1024) + 'MB)');
      this.resetInput();
      return;
    }

    // 清理先前的预览内存
    if (this.currentBlobUrl) {
      URL.revokeObjectURL(this.currentBlobUrl);
    }

    // 生成新的本地即时预览
    this.currentBlobUrl = URL.createObjectURL(file);
    this.previewImg.src = this.currentBlobUrl;
    this.previewImg.style.display = 'block';
    this.uploadBtn.disabled = false;
    this.statusText.textContent = `已选择: ${file.name} (${(file.size / 1024).toFixed(1)} KB)`;
  }

  async upload() {
    const file = this.fileInput.files[0];
    if (!file) return;

    const formData = new FormData();
    // 关键:字段名 'image' 须与后端保持一致
    formData.append('image', file, file.name);
    // 可选:附带额外业务参数
    formData.append('uploadedAt', Date.now().toString());

    // 准备 AbortController 支持 30 秒超时熔断
    this.abortController = new AbortController();
    const timeoutId = setTimeout(() => this.abortController.abort(), 30000);

    try {
      this.setLoading(true, '上传中,请稍候...');

      const response = await fetch(this.uploadUrl, {
        method: 'POST',
        body: formData,
        signal: this.abortController.signal
        // 绝不手动加 Content-Type
      });

      clearTimeout(timeoutId);

      // 显式校验 HTTP 状态码
      if (!response.ok) {
        throw new Error(`服务响应异常: HTTP ${response.status}`);
      }

      const data = await response.json();
      
      // 假定服务端响应协议规范: { code: 0, data: { url: '...' }, msg: 'success' }
      if (data.code === 0) {
        this.statusText.textContent = '上传成功!';
        // 用真实远程地址替换本地临时 Blob 预览
        this.previewImg.src = data.data.url;
        this.cleanUpBlob();
        this.resetInput();
      } else {
        throw new Error(data.msg || '业务接口处理失败');
      }
    } catch (error) {
      if (error.name === 'AbortError') {
        this.statusText.textContent = '上传超时,请检查网络后重试';
      } else {
        this.statusText.textContent = `上传失败: ${error.message}`;
      }
      console.error('Upload Error:', error);
    } finally {
      this.setLoading(false);
    }
  }

  cleanUpBlob() {
    if (this.currentBlobUrl) {
      URL.revokeObjectURL(this.currentBlobUrl);
      this.currentBlobUrl = null;
    }
  }

  resetInput() {
    this.fileInput.value = '';
    this.uploadBtn.disabled = true;
  }

  setLoading(isLoading, msg = '') {
    this.uploadBtn.disabled = isLoading;
    this.fileInput.disabled = isLoading;
    if (msg) this.statusText.textContent = msg;
  }
}

服务端接收规范示意(以 Node.js Express + Multer 为例)

前后端协同的重点在于表单字段名(Field Name)的一致性。如果在前端通过 formData.append('image', file) 提交,后端对应也必须以此字段接收:

// Node.js 服务端示例代码
const express = require('express');
const multer = require('multer');
const upload = multer({ dest: 'uploads/' });
const app = express();

// 单文件上传路由,'image' 与前端 append 的第一个参数严格对齐
app.post('/api/upload', upload.single('image'), (req, res) => {
  if (!req.file) {
    return res.status(400).json({ code: 1, msg: '未接收到图片文件' });
  }

  // 正常落盘或转存到对象存储 (OSS/S3)
  const fileUrl = `/uploads/${req.file.filename}`;
  res.json({
    code: 0,
    msg: 'success',
    data: {
      url: fileUrl,
      size: req.file.size,
      mimetype: req.file.mimetype
    }
  });
});

批量多图上传的扩展

如果需要支持多选(<input type="file" multiple>),只需在 FormData 中循环追加即可。

const files = fileInput.files;
const formData = new FormData();

// 循环追加同名或数组键名的文件
for (let i = 0; i < files.length; i++) {
  formData.append('photos[]', files[i]);
}

// 一次性通过 Fetch 提交给服务端的 upload.array('photos[]')
fetch('/api/upload-multiple', {
  method: 'POST',
  body: formData
});

五、全景总结与高频避坑排查矩阵

为了帮助开发者在遇到问题时能够快速定位根因,我们将整个原生上传过程中的核心关注点与高频陷阱归纳为以下四个维度的检查矩阵。

原生JS使用Fetch和FormData实现图片上传
图 4:原生图片上传四大链路全景矩阵与避坑清单

如果在调试过程中遇到异常,请按以下步骤逐一排查:

  1. 打印 FormData 显示为空? 许多开发者使用 console.log(formData) 试图观察其内部内容,却只看到一个空的 FormData {} 原型对象。这是正常现象,因为其内部数据存储在浏览器的隐式槽中。若要检查内容,请通过迭代器查看:
    for (const [key, value] of formData.entries()) {
      console.log(key, value); // 能清晰看到 field 名字和对应的 File 实例
    }
  2. 选择同一张图片时 change 事件不触发? 在取消或成功上传后,如果不手动清空 fileInput.value = '',当用户再次选择与上次路径相同的文件时,浏览器认为“值未改变”,将不会触发 change 监听。
  3. 服务端报错 413 Request Entity Too Large? 这是网关或反向代理层的限制。例如 Nginx 默认配置的 client_max_body_size 仅为 1MB。若上传稍大的原图,请求根本无法触达业务后端,需要在 Nginx 配置中适当调高该阈值(如 client_max_body_size 20m;)。
  4. 为什么接口返回 404 或 500 时 Fetch 没有进入 catch 块? fetch() 返回的 Promise 只会在网络断开或请求被主动取消(Abort)时被 reject。只要收到了服务端的 HTTP 响应头(即使状态码是 404、500 甚至 502),Promise 都会正常 resolve。因此,必须在拿到响应的第一时间显式调用 if (!response.ok) throw new Error(...) 才能正确引导异常流进入 catch。

实用工具推荐

电子包浆

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

使用 ›
图片压缩

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

使用 ›
相关文章