@julylb/image-compress

浏览器端图片压缩工具，支持最大宽高限制、最大大小限制和大小超限后的体积优先重试。

安装

npm install @julylb/image-compress

本包依赖浏览器能力，不支持 Node.js 服务端压缩。

基础用法

import { compressImage } from '@julylb/image-compress';

const result = await compressImage(file, {
  maxWidth: 1600,
  maxHeight: 1600,
  maxSizeMB: 1,
  mode: 'speed',
  format: 'auto',
});

console.log(result.blob, result.width, result.height, result.compressedSize);

compressImage 的第一个参数支持 File、Blob、base64 字符串、data URL、HTTP/HTTPS 图片链接、blob: 链接和相对路径图片链接。图片链接会通过浏览器 fetch 拉取，因此跨域图片需要目标资源允许 CORS。

参数

第一个参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | file | File \| Blob \| string | 待压缩图片。字符串支持 base64、data URL 和图片链接 |

第二个参数

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | maxWidth | number | 0 | 最大输出宽度，0 表示不限制 | | maxHeight | number | 0 | 最大输出高度，0 表示不限制 | | customWidth | number | 不设置 | 指定输出宽度，需要和 customHeight 同时设置；生效时会强制输出指定宽高，允许图片变形 | | customHeight | number | 不设置 | 指定输出高度，需要和 customWidth 同时设置；生效时会强制输出指定宽高，允许图片变形 | | maxSizeMB | number | 0 | 最大输出大小，单位 MB，0 表示不限制 | | mode | string | speed | 压缩模式：speed、balanced、quality、small | | format | string | auto | 输出格式：auto、jpeg、png、webp、avif；auto 会优先按输入 MIME 或文件扩展名输出，无法判断时输出 webp | | quality | number | 模式默认值 | 压缩质量，1 到 100 | | timeout | number | 120000 | 单次 worker 超时时间，单位毫秒 | | createWorker | Function | 内置 worker | 自定义 worker 创建方法 |

返回值

{
  blob,
  format,
  requestedFormat,
  actualMimeType,
  width,
  height,
  originalWidth,
  originalHeight,
  compressedSize,
  durationMs,
  attempts,
  encoder,
  mode,
  quality,
  sizeLimited
}

返回值提供压缩后的 blob，不会自动生成 blobUrl。如果需要用于图片预览，可以自行调用 URL.createObjectURL(result.blob)。

attempts 会记录每次压缩尝试的模式、质量、大小、宽高、耗时和编码器。

最大宽高规则

maxWidth 和 maxHeight 表示压缩后的图片宽高上限。原图超过任意一个上限时，会按比例缩小，直到宽高都不超过限制；不会放大小图。

如果同时设置 customWidth 和 customHeight，会优先强制输出指定宽高，不保持原图比例，因此图片可能变形。只设置其中一个时不会生效，会继续按 maxWidth 和 maxHeight 的规则处理。

最大大小规则

设置 maxSizeMB 后，首次压缩结果如果仍超过限制，会自动切换到体积优先模式再次压缩。若仍超限，会逐步降低质量继续重试，直到满足大小限制或达到最低质量。

maxSizeMB 是尽力达成的限制。极端图片在最低质量下仍可能超过上限，此时会返回已尝试后的最小结果，并通过 attempts 和 sizeLimited 告知调用方。

Worker 兼容

默认用法会在包内创建 module worker：

new Worker(new URL('./worker.js', import.meta.url), { type: 'module' })

Vite 通常可以直接处理。若 Webpack、Rollup 或自定义构建链无法正确解析包内 worker，可以传入 createWorker：

const result = await compressImage(file, {
  createWorker: () => new Worker(new URL('./custom-worker.js', import.meta.url), { type: 'module' }),
});

自定义 worker 需要复用或转发本包的 @julylb/image-compress/worker 入口。

本地打包验证

npm pack --dry-run

正式发布前建议先在业务项目中安装 npm pack 生成的 tarball 验证 worker 和 WASM 资源加载。