JS原生Canvas实现图片压缩并上传的完整代码

作者:白露

时间:2026-11-19

浏览:200

使用原生JavaScript与HTML5 Canvas在客户端实现图片等比尺寸缩放与质量压缩,并结合FormData和Fetch API完成异步上传的完整代码与深度原理解析。

文章目录
在Web开发中,直接上传移动端或数码相机拍摄的原图常常面临文件过大(数十兆字节)、耗尽移动蜂窝网络流量以及服务端处理带宽拥堵的问题。解决这一问题的标准工程路径是:在用户选中文件后,利用纯原生JavaScript结合HTML5 Canvas将图片在浏览器端进行等比尺寸缩放与有损重采样编码,转为轻量级Blob二进制对象后再推往服务端。本文提供立即可用的完整HTML与JavaScript单文件运行代码,并深入讲解每一步的技术细节、尺寸计算逻辑与边界陷阱。
JS原生Canvas实现图片压缩并上传的完整代码
技术架构导览:从原始文件读取、Canvas内存等比降采样、Blob输出到网络传输的全链路流转

一、完整可执行示例代码

下面是一份包含完整用户交互界面、拖拽与点选监听、Canvas等比压缩处理、以及模拟上传进度的单文件完整HTML代码。代码不依赖任何外部第三方库,直接使用浏览器现代原生API编写。你可以将其保存为 index.html 并直接在浏览器中打开运行。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>原生Canvas图片压缩与上传示例</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      max-width: 640px;
      margin: 40px auto;
      padding: 0 20px;
      color: #333;
    }
    .upload-box {
      border: 2px dashed #456581;
      border-radius: 8px;
      padding: 32px;
      text-align: center;
      background: #F7F9FB;
      cursor: pointer;
      transition: border-color 0.2s, background-color 0.2s;
    }
    .upload-box.dragover {
      border-color: #438A80;
      background-color: #E8F4F2;
    }
    .file-input {
      display: none;
    }
    .info-panel {
      margin-top: 24px;
      padding: 16px;
      border: 1px solid #E2E8F0;
      border-radius: 6px;
      background: #FFFFFF;
      font-size: 14px;
      display: none;
    }
    .info-row {
      margin-bottom: 8px;
      display: flex;
      justify-content: space-between;
    }
    .preview-img {
      max-width: 100%;
      height: auto;
      border-radius: 4px;
      margin-top: 12px;
      border: 1px solid #CBD5E1;
    }
    .status-text {
      margin-top: 12px;
      font-weight: bold;
      color: #438A80;
    }
  </style>
</head>
<body>

  <h2>本地图片压缩并上传</h2>

  <!-- 点击与拖拽上传区域 -->
  <div class="upload-box" id="dropArea">
    <p>点击选择图片,或将图片拖拽到此处</p>
    <input type="file" id="fileInput" class="file-input" accept="image/*">
  </div>

  <!-- 信息展示面板 -->
  <div class="info-panel" id="infoPanel">
    <div class="info-row">
      <span>原始文件名:</span>
      <strong id="origName">-</strong>
    </div>
    <div class="info-row">
      <span>原始体积:</span>
      <strong id="origSize">-</strong>
    </div>
    <div class="info-row">
      <span>压缩后体积:</span>
      <strong id="compSize" style="color: #438A80;">-</strong>
    </div>
    <div class="info-row">
      <span>体积缩减比率:</span>
      <strong id="ratio">-</strong>
    </div>
    <div class="status-text" id="statusText">准备就绪</div>
    <img id="previewImage" class="preview-img" alt="压缩后预览">
  </div>

  <script>
    /**
     * 核心函数:使用 Canvas 压缩本地图片
     * @param {File} file - 用户选中的 File 对象
     * @param {Object} options - 压缩参数配置
     * @param {number} [options.maxWidth=1920] - 允许的最大宽度
     * @param {number} [options.maxHeight=1080] - 允许的最大高度
     * @param {number} [options.quality=0.8] - JPEG/WEBP 压缩质量 (0~1)
     * @param {string} [options.mimeType='image/jpeg'] - 输出的目标 MIME 类型
     * @returns {Promise<Blob>} 压缩后的二进制 Blob 对象
     */
    function compressImage(file, options = {}) {
      const {
        maxWidth = 1920,
        maxHeight = 1080,
        quality = 0.8,
        mimeType = 'image/jpeg'
      } = options;

      return new Promise((resolve, reject) => {
        // 1. 验证传入文件是否为图片类型
        if (!file || !file.type.startsWith('image/')) {
          reject(new Error('传入的文件不是有效的图片格式'));
          return;
        }

        // 2. 利用轻量级 Object URL 创建本地内存链接
        const objectUrl = URL.createObjectURL(file);
        const img = new Image();

        img.onload = () => {
          // 图片装载成功后释放 Object URL
          URL.revokeObjectURL(objectUrl);

          const originWidth = img.naturalWidth;
          const originHeight = img.naturalHeight;

          // 3. 计算等比缩放后的目标尺寸
          let targetWidth = originWidth;
          let targetHeight = originHeight;

          if (originWidth > maxWidth || originHeight > maxHeight) {
            const widthRatio = originWidth / maxWidth;
            const heightRatio = originHeight / maxHeight;

            if (widthRatio > heightRatio) {
              // 宽度超标更显著,以宽度为基准缩小
              targetWidth = maxWidth;
              targetHeight = Math.round(originHeight / widthRatio);
            } else {
              // 高度超标更显著,以高度为基准缩小
              targetHeight = maxHeight;
              targetWidth = Math.round(originWidth / heightRatio);
            }
          }

          // 4. 创建离屏 Canvas
          const canvas = document.createElement('canvas');
          canvas.width = targetWidth;
          canvas.height = targetHeight;
          const ctx = canvas.getContext('2d');

          if (!ctx) {
            reject(new Error('获取 Canvas 2D 上下文失败'));
            return;
          }

          // 5. 若输出为 JPEG,填充白色背景防止透明 PNG 转码后底色发黑
          if (mimeType === 'image/jpeg') {
            ctx.fillStyle = '#FFFFFF';
            ctx.fillRect(0, 0, targetWidth, targetHeight);
          }

          // 6. 执行图像重采样绘制
          ctx.drawImage(img, 0, 0, targetWidth, targetHeight);

          // 7. 将 Canvas 内容导出为标准二进制 Blob 实体
          canvas.toBlob(
            (blob) => {
              if (blob) {
                resolve(blob);
              } else {
                reject(new Error('Canvas 转换为 Blob 失败'));
              }
            },
            mimeType,
            quality
          );
        };

        img.onerror = () => {
          URL.revokeObjectURL(objectUrl);
          reject(new Error('图片加载解析失败'));
        };

        img.src = objectUrl;
      });
    }

    /**
     * 上传函数:将压缩后的 Blob 追加至 FormData 并发送网络请求
     * @param {Blob} blob - 压缩后的图片 Blob
     * @param {string} fileName - 上传时保留的文件名
     * @param {string} uploadUrl - 后端上传接口地址
     * @returns {Promise<any>}
     */
    async function uploadCompressedImage(blob, fileName, uploadUrl) {
      const formData = new FormData();
      // append 的第三个参数可指定传输给后端的文件名
      formData.append('file', blob, fileName);

      // 发起 fetch 异步请求
      const response = await fetch(uploadUrl, {
        method: 'POST',
        body: formData
        // 注意:切勿手动设置 'Content-Type': 'multipart/form-data',
        // 浏览器会自动计算边界字符串 boundary
      });

      if (!response.ok) {
        throw new Error(`上传失败,服务端状态码: ${response.status}`);
      }

      return await response.json();
    }

    // --- 页面交互绑定逻辑 ---
    const dropArea = document.getElementById('dropArea');
    const fileInput = document.getElementById('fileInput');
    const infoPanel = document.getElementById('infoPanel');
    const origName = document.getElementById('origName');
    const origSize = document.getElementById('origSize');
    const compSize = document.getElementById('compSize');
    const ratioText = document.getElementById('ratio');
    const statusText = document.getElementById('statusText');
    const previewImage = document.getElementById('previewImage');

    function formatBytes(bytes) {
      if (bytes === 0) return '0 B';
      const k = 1024;
      const sizes = ['B', 'KB', 'MB', 'GB'];
      const i = Math.floor(Math.log(bytes) / Math.log(k));
      return (bytes / Math.pow(k, i)).toFixed(2) + ' ' + sizes[i];
    }

    async function handleFileProcess(file) {
      if (!file) return;

      infoPanel.style.display = 'block';
      origName.textContent = file.name;
      origSize.textContent = formatBytes(file.size);
      compSize.textContent = '压缩计算中...';
      ratioText.textContent = '-';
      statusText.textContent = '正在本地 Canvas 中重采样...';

      try {
        const startTime = performance.now();
        // 执行压缩:最大宽度 1920,质量 0.8
        const compressedBlob = await compressImage(file, {
          maxWidth: 1920,
          maxHeight: 1080,
          quality: 0.8,
          mimeType: 'image/jpeg'
        });
        const costTime = Math.round(performance.now() - startTime);

        compSize.textContent = formatBytes(compressedBlob.size);
        const percent = ((1 - compressedBlob.size / file.size) * 100).toFixed(1);
        ratioText.textContent = `减小了 ${percent}% (耗时 ${costTime}ms)`;

        // 展示预览
        const previewUrl = URL.createObjectURL(compressedBlob);
        previewImage.src = previewUrl;

        statusText.textContent = '本地压缩完成,正在向后端投递...';

        // 模拟执行上传(实际开发中替换为真实接口路径)
        // await uploadCompressedImage(compressedBlob, 'compressed_' + file.name, '/api/upload');
        statusText.textContent = '上传成功(当前为单机演示模式,已成功生成 Blob 实体)';
      } catch (err) {
        statusText.textContent = '处理失败: ' + err.message;
        statusText.style.color = '#DC2626';
      }
    }

    dropArea.addEventListener('click', () => fileInput.click());
    fileInput.addEventListener('change', (e) => {
      const file = e.target.files[0];
      handleFileProcess(file);
    });

    // 拖拽高亮与文件接收
    dropArea.addEventListener('dragover', (e) => {
      e.preventDefault();
      dropArea.classList.add('dragover');
    });
    dropArea.addEventListener('dragleave', () => dropArea.classList.remove('dragover'));
    dropArea.addEventListener('drop', (e) => {
      e.preventDefault();
      dropArea.classList.remove('dragover');
      if (e.dataTransfer.files && e.dataTransfer.files.length > 0) {
        handleFileProcess(e.dataTransfer.files[0]);
      }
    });
  </script>
</body>
</html>

二、核心操作步骤与执行流程

整个客户端压缩与上传的生命周期可以清晰地划分为五个紧密衔接的步骤。理解这个流转过程有助于排查实际开发中的异步时序与内存问题。

JS原生Canvas实现图片压缩并上传的完整代码
图 1:原生 Canvas 图片压缩与上传的核心处理步骤流水线

步骤 1:获取 File 并创建轻量内存引用

用户通过文件选择框或拖拽交互获得 File 实例后,传统做法是调用 FileReader.readAsDataURL() 将文件读取为庞大的 Base64 字符串。但更优雅、高性能的原生方式是使用 URL.createObjectURL(file)。该方法会同步生成一个形如 blob:null/xxx 的轻量级内存指针,完全不涉及数据的解码与内存拷贝,执行速度接近 0 毫秒。

步骤 2:Image 异步载入与尺寸判断

新建 new Image() 并将其 src 指向上一步生成的内存地址。必须在 img.onload 回调中读取 img.naturalWidth 与 img.naturalHeight,获取图片未经 CSS 影响的真实物理像素宽高。在此阶段根据预设的 maxWidth 与 maxHeight 进行等比尺寸换算。

步骤 3:离屏 Canvas 重绘与背景预处理

使用 document.createElement('canvas') 创建一个脱离 DOM 树的离屏画布,将计算得出的目标尺寸显式赋值给 canvas.width 与 canvas.height。如果输出目标为 image/jpeg,需先用白色填充画布矩形,然后再调用 ctx.drawImage(img, 0, 0, targetWidth, targetHeight)。浏览器会在这一阶段调用底层图形硬件的插值算法完成降采样。

步骤 4:异步导出二进制 Blob 对象

调用 canvas.toBlob(callback, mimeType, quality)。该方法由浏览器工作线程异步执行有损压缩编码,将压缩质量参数(通常设为 0.75 到 0.85)应用到像素矩阵中,并在完成后通过回调函数返回纯粹的 Blob 二进制数据块。

步骤 5:构建 FormData 载荷与网络提交

实例化原生 FormData,使用 formData.append('file', blob, fileName) 将压缩后的二进制流注入,最后通过 fetch 或 XMLHttpRequest 发送 POST 请求。传输完成后,及时销毁不再使用的临时对象指针。

三、核心原理:等比缩放计算与边界判定

图片压缩的关键前提是降低分辨率(降采样)。现代手机拍摄的照片原始分辨率常常超过 4000×3000 像素,若不缩小尺寸而仅降低编码质量,文件体积的缩减极为有限。等比缩放的核心要求是在限制最大宽度与最大高度的同时,保持原图的高宽比例不变,防止拉伸变形。

JS原生Canvas实现图片压缩并上传的完整代码
图 2:画布等比缩放计算决策矩阵与几何约束关系

等比尺寸判定的计算数学推导如下:

  • 获取比例系数: 计算原图宽高比 aspectRatio = originWidth / originHeight。同时计算宽比 widthRatio = originWidth / maxWidth 与高比 heightRatio = originHeight / maxHeight。
  • 判定缩放主导轴:
    • 如果 widthRatio > 1 且 widthRatio >= heightRatio,说明图片的横向超出比例更严重(扁平形照片)。此时必须将目标宽度直接锁定为 maxWidth,目标高度按比例计算为 Math.round(originHeight / widthRatio)。
    • 如果 heightRatio > 1 且 heightRatio > widthRatio,说明图片的纵向超出比例更严重(高瘦形照片)。此时必须将目标高度锁定为 maxHeight,目标宽度按比例计算为 Math.round(originWidth / heightRatio)。
  • 小图保护策略: 如果 originWidth <= maxWidth 且 originHeight <= maxHeight,则 targetWidth 与 targetHeight 保持原始尺寸不变,避免对小图进行不必要的拉伸导致画面虚焦变糊。

四、关键机制对比:toBlob 与 toDataURL 的深层差异

不少开发者习惯使用 canvas.toDataURL() 获取 Base64 字符串后再进行传输,但在中大型图片上传的生产环境中,这种方式存在严重的性能缺陷。

JS原生Canvas实现图片压缩并上传的完整代码
图 3:导出机制对比:canvas.toBlob (推荐) vs canvas.toDataURL
对比维度 canvas.toBlob (推荐) canvas.toDataURL (不推荐用于大图)
输出形式 二进制原生 Blob 对象 以 data:image/jpeg;base64,... 开头的长字符串
数据体积 原始真实二进制大小,无额外开销 由于 Base64 编码机制,体积膨胀约 33%
线程开销 异步非阻塞,由浏览器内核后台线程编码 同步阻塞,在大尺寸图片编码时主线程会掉帧卡顿
内存占用 内存利用率高,生命周期由 V8 引用计数托管 产生巨大的字符串常量,容易触发移动设备 OOM 崩溃
上传适配 直接 append 进 FormData,与常规文件完全一致 需后端专门写解码逻辑,或前端再次用 atob 转回二进制

五、常见问题与工程避坑指南

JS原生Canvas实现图片压缩并上传的完整代码
图 4:原生 Canvas 图片压缩工程化关键要点与避坑速查

1. 为什么对 PNG 图片设置 quality 参数没有任何效果?

根据 W3C HTML5 Canvas 标准规范,image/png 是一种无损压缩格式,toBlob() 和 toDataURL() 的第三个参数 quality 仅对有损压缩格式有效(如 image/jpeg、image/webp)。如果传入 image/png,浏览器会静默忽略质量参数,产出的 PNG 文件体积往往与原图相差无几甚至更大。

工程对策

如果不需要透明通道,在压缩时统一将输出目标格式设定为 image/jpeg;若业务允许且浏览器支持现代格式,也可以使用压缩率更优秀的 image/webp。

2. 透明背景 PNG 转成 JPEG 后底色为什么变黑?

Canvas 在初始化时未绘制任何内容的区域默认是完全透明的黑色(RGBA 值为 [0, 0, 0, 0])。当我们将 Canvas 内容导出为不支持透明通道的 JPEG 格式时,透明通道(Alpha)会被直接丢弃,原有的 [0, 0, 0] RGB 颜色显露出来,导致所有原本透明的区域呈现死黑色。

修复方法

在调用 ctx.drawImage() 之前,必须先将整个画布铺满白色背景:

ctx.fillStyle = '#FFFFFF'; ctx.fillRect(0, 0, canvas.width, canvas.height);

3. 单页应用 (SPA) 中内存泄露的防范

使用 URL.createObjectURL() 生成的本地链接会驻留在浏览器内存中,直到关联的 document 被卸载。在单页应用中,如果用户频繁批量上传图片,长期不释放这些 Object URL 会导致页面内存持续攀升。

规范做法

只要 img.onload 触发、图像数据已经成功装载入 DOM Image 对象后,立刻调用 URL.revokeObjectURL(url) 撤销引用,让浏览器及时进行垃圾回收。

4. 发送 FormData 时切勿手动设置 Content-Type

在使用 fetch 或 axios 发送包含 Blob 的 FormData 时,新手开发者常犯的错误是显式添加头部 'Content-Type': 'multipart/form-data'。这样做会导致请求头中缺失浏览器动态生成的 boundary 隔离字符串(例如 boundary=----WebKitFormBoundaryXYZ),服务端无法正确解析表单分界,从而报 400 Bad Request 或解析出空文件。

正确规则

将 body 设为 FormData 实例即可,完全不要在 headers 中声明 Content-Type,浏览器会自动附加带有合法 boundary 的完整头信息。

六、总结

使用纯原生 JavaScript 实现客户端图片压缩上传的核心脉络十分清晰:以 URL.createObjectURL 完成高效内存绑定,以离屏 Canvas 的 drawImage 完成像素硬件插值等比缩小,以 canvas.toBlob 异步输出高压缩比的二进制流,最后借助 FormData 与 fetch 完成异步上传。整个过程摆脱了沉重的第三方库依赖,极大缩减了移动端上传等待时间与网络流量消耗,是Web前端处理图像上传的高性能标准解法。

实用工具推荐

电子包浆

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

使用 ›
图片压缩

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

使用 ›
相关文章