更新记录

1.0.0（2026-10-09）

2026-10-09

• 首个版本发布
• Android 端：基于 BitmapFactory + Bitmap.compress 实现压缩，inJustDecodeBounds 只读尺寸、inSampleSize 降采样防 OOM
• iOS 端：基于 UIGraphicsImageRenderer 重绘缩放 + UIImage.jpegData / pngData 编码
• 鸿蒙端：基于 @kit.ImageKit 的 PixelMap + image.createImagePacker 编码
• 提供 compress / compressToBase64 / resize / convertFormat / getImageInfo 五个接口
• 返回压缩率与真实输出尺寸，便于业务侧判断是否需要二次压缩
• web 与小程序端降级到 Canvas 重绘路径，并提供 compressAsync 异步接口
• webp 在无编码能力的平台（iOS / 鸿蒙 / API<30 的 Android）自动降级为 jpg，并在返回值中回写真实格式

平台兼容性

uni-app(3.99)

其他

图片压缩（czg-imgcomp）

原生图片压缩与格式转换。App 端走 uts 原生实现（Android Bitmap / iOS UIGraphicsImageRenderer /鸿蒙 PixelMap），大图先降采样再压缩，避免一次性读入内存导致 OOM；web 与小程序端自动降级到 Canvas 重绘路径。

为什么不用现成方案

本插件的取舍：先按最长边降采样，再按目标质量重编码，与原生图片管线（Android decode→sample→encode）的做法一致，并额外返回压缩率与真实输出尺寸，方便业务侧判断是否需要二次压缩。

特性

• 原生实现：App 端不经过 JS 引擎，大图处理不卡 UI
• 降采样防OOM：Android 用 inSampleSize、鸿蒙用 desiredSize、iOS 用 UIGraphicsImageRenderer 重绘，均在解码阶段降分辨率
• 只读尺寸不占内存：读取图片信息走 inJustDecodeBounds / getImageInfoSync，不分配像素缓冲
• 真实结果度量：返回压缩后字节数、尺寸、压缩率，ratio 可直接用于判断是否需要再压
• 格式协商：请求 webp 但平台无编码能力时（iOS、鸿蒙）自动降级为 jpg，并在返回值的 format 中回写真实格式，不静默产出错格式
• 全端可用：App 端原生实现；web / 小程序降级到 Canvas，接口一致

安装

在插件市场搜索「图片压缩」或插件 ID czg-imgcomp，点击「使用 HBuilderX 导入插件」；或把 g-imgcomp 目录放入工程 uni_modules/ 下。

App 端需先用 HBuilderX 制作自定义基座，uts 插件才能运行。详见 uts 插件使用说明。

用法

import { compress, compressToBase64, resize, convertFormat, getImageInfo }
  from '@/uni_modules/g-imgcomp/index.native.js'

// 1. 读图片信息（不占内存，可安全用于列表预加载）
const info = getImageInfo('/path/to/photo.jpg')
console.log(info.width, info.height, info.size, info.format)

// 2. 压缩到文件（质量 70 + 最长边不超过 1080）
const r = compress('/path/to/photo.jpg', {
  quality: 70,
  format: 'jpg',
  maxEdge: 1080,
  outPath: '/path/to/photo_min.jpg'
})
console.log(r.size)   // 压缩后字节数
console.log(r.ratio)  // 压缩率，如 0.18 表示压到原来的 18%

// 3. 压缩成 base64（直接塞进 JSON 字段）
const b64 = compressToBase64('/path/to/photo.jpg', {
  quality: 60,
  maxEdge: 640
})

// 4. 仅缩放，不重编码（保画质）
const rz = resize('/path/to/photo.jpg', 1280, '/path/to/photo_1280.jpg')

// 5. 格式转换
const cv = convertFormat('/path/to/photo.png', 'jpg', '/path/to/photo.jpg')

web / 小程序端

Canvas 导出本身是异步接口，所以压缩统一走 Promise：

import { compressAsync } from '@/uni_modules/g-imgcomp/index.js'

const r = await compressAsync('/path/to/photo.jpg', {
  quality: 70,
  format: 'jpg',
  maxEdge: 1080
})
console.log(r.path)  // 压缩后临时文件路径

web / 小程序端调用同步的 compress() 会抛出错误并提示改用 compressAsync()， 这是刻意设计——同步接口在非App 端没有等价实现，返回假结果比报错更糟。

API 清单

CompressOptions

平台支持与能力差异

Android 从 API 30 起原生支持 WebP 编码，低于 API 30 的设备请求 webp 时会回退为 jpg，返回值 format 为真实格式。若业务必须保证 webp，建议在 Android 端加最低版本约束：

"app-plus": { "android": { "minSdkVersion": 21 } }

错误码

注意事项

• ratio > 1 表示压缩后反而变大了（典型场景：小图 +高 quality + PNG）。此时建议改小 quality 或不再压缩。
• 二次压缩会累积画质损失。若目标是把 2MB 降到 200KB，一次把 quality 设到 50~60通常优于两次各压80。
• PNG 无损，压缩只能靠缩小尺寸来减小体积。需要减小体积请用 jpg。
• 输入路径为 App 本地文件路径（plus.io.convertLocalFileSystemURL 或 uni.saveFile 的返回值），不是网络 URL。

价格

普通授权版由 DCloud 对 uts 源码加密保护，运行时经云端解密编译；源码授权版提供完整 uts 源码，可自行修改与扩展，同样享受后续版本升级。

隐私说明

本插件全部图片处理在本机完成，不联网、不采集、不上传任何图片或数据。插件不主动读取相册与存储目录，输入完全由调用方通过参数传入。隐私声明详见 package.json 的 dcloudext.declaration。

更新日志

见 changelog.md

开源协议

MIT