zf-img-compress

浏览器端图片多级压缩工具 适配证件、发票、带文字截图，压缩策略：优先降低画质，万不得已才缩小分辨率，支持自定义图片最小宽高像素，可开关压缩过程控制台打印日志。

特性

1. 先降画质、后缩尺寸，最大限度保留单据文字清晰度
2. 支持自定义图片最小宽高 minPixel，默认800px
3. iOS超大画布自动预缩放，防止浏览器崩溃
4. 原图体积达标直接跳过压缩，节省性能
5. 可通过 compressConsole 控制是否输出压缩迭代日志
6. 纯Canvas实现，零第三方依赖，兼容uni-app H5 / 普通网页

安装

npm install zf-img-compress



API 文档
compressImage(filePath, tempFile, options)
主入口方法，自动判断原图大小，小文件直接放行。
表格
参数	类型	必填	默认值	说明
filePath	string	是	-	图片临时 blob 路径
tempFile	File	是	-	图片原始 File 对象
options	Object	否	{}	压缩配置项
options.maxSize	Number	否	500 * 1024	文件最大字节上限，默认 500KB
options.compressConsole	Boolean	否	false	是否开启控制台打印日志
options.minPixel	Number	否	800	缩小图片时的最小宽高像素
返回结果
javascript
运行
{
  file: File,
  filePath: string,
  size: number
}

compressH5Image(imagePath, options)
底层核心压缩方法，仅传入图片路径，适合单独处理 blob 图片。
配置参数与上面完全一致。
使用示例
1. 默认配置（关闭日志、500KB 上限、最小 800px）
javascript
运行
import compressImage from 'img-compress-tool'

uni.chooseImage({
  count: 1,
  sourceType: ['album', 'camera'],
  success: async (res) => {
    const tempPath = res.tempFilePaths[0]
    const tempFile = res.tempFiles[0]
    try {
      const result = await compressImage(tempPath, tempFile, {
        maxSize: 500 * 1024
      })
      console.log('压缩完成', result.size)
    } catch (err) {
      console.error('压缩失败', err.message)
    }
  }
})

2. 开发调试：开启打印日志
javascript
运行
const result = await compressImage(tempPath, tempFile, {
  maxSize: 1024 * 1024,
  compressConsole: true
})

3. 证件发票场景：拉高最小像素，文字更清晰
javascript
运行
const result = await compressImage(tempPath, tempFile, {
  maxSize: 1024 * 1024,
  minPixel: 1200,
  compressConsole: true
})

4. 风景照片：放宽最低像素
javascript
运行
const result = await compressImage(tempPath, tempFile, {
  maxSize: 2 * 1024 * 1024,
  minPixel: 600
})

5. 单独调用底层压缩函数
javascript
运行
import { compressH5Image } from 'img-compress-tool'

async function onlyCompress() {
  const blobUrl = 'blob:xxxx'
  const res = await compressH5Image(blobUrl, {
    minPixel: 900,
    maxSize: 800 * 1024
  })
}

日志输出样例
plaintext
[原图大小] 10485760 10.00MB
【第1次压缩】当前文件大小：820340 801.11KB，已耗时：32ms
【第2次压缩】当前文件大小：752130 734.50KB，已耗时：56ms
【第3次压缩】达标，终止压缩！本轮总耗时：89ms = 0.089 秒

注意事项
仅支持浏览器、uni-app H5 环境，不兼容微信小程序原生。
输出图片格式统一为 jpeg。
缩小至 minPixel 仍无法压到上限，会抛出异常：图片体积过大，请裁剪多余空白后重新上传。
超大原图会自动缩小一级，防止 iOS 浏览器画布崩溃。
plaintext

---

### 二、为什么粘贴后格式失效？问题解决办法
1. **不要在网页预览框里复制**
网页代码预览框会自动把换行、空格吃掉，纯语法会被破坏。

2. **正确操作**
1）全选上面整段文字（从`# img-compress-tool`一直拉到最后一行）；
2）Ctrl+C；
3）打开VSCode，新建空白README.md；
4）粘贴；
5）切换到「预览视图」，标题、表格、代码块自动渲染。

### 三、语法校验（每一项都是标准MD）
- 一级标题：`# 标题`
- 二级标题：`## 标题`
- 表格：标准markdown表格语法，GitHub/Gitee完美兼容
- 代码块：前后三个反引号 ```，js代码块自动高亮
只要粘贴到纯空白文件，格式100%正常。