更新记录

0.1.0（2026-10-13） 下载此版本

• Android 单张 JPEG/PNG 本地压缩，固定输出 JPEG。
• 目标字节数与最大宽高限制，返回实际字节数、尺寸和达标状态。
• 8 种 EXIF 方向处理、透明区域白底、后台串行处理和缓存清理。
• 示例修复原生缓存路径的预览，增加图片放大查看、相册保存及失败提示。
• HBuilderX 5.26 / 传统 uni-app / Vue 3，vivo V2454A 真机功能测试通过；不声明 uni-app x 或其他平台兼容。

平台兼容性

uni-app(5.26)

轻羽 Core · Android 图片定体积压缩

0.1.0，插件目录 ID 为 qingyu-imagecompress。MIT 许可，免费。已在 vivo V2454A 真机完成选图、压缩、结果预览和相册保存流程测试。

功能与支持范围

单张本地 JPEG/PNG → JPEG，限制字节数和最大宽高，修正 EXIF 的旋转与镜像方向，透明区域统一使用 白色 #FFFFFF 背景。返回真实输出路径、文件字节数、输出尺寸及是否达标。传统 uni-app 预览或保存 Android 原生绝对路径时，先转换为 file:// URI，例如 const imagePath = result.outputPath.startsWith('/') ? 'file://' + result.outputPath : result.outputPath，再用于 <image>、uni.previewImage 或 uni.saveImageToPhotosAlbum。原图不修改；输出不保留 EXIF、GPS 等原始元数据。

只支持 Android 的传统 uni-app / Vue 3，已在 HBuilderX 5.26 自定义基座运行验证。uni-app x 尚未验收，不声明支持。不要用于 iOS、鸿蒙、Web、小程序，不支持 HEIC、批量压缩。最低 Android 配置为 API 23（实现下限，尚非实测兼容承诺）。本次发布要求 HBuilderX / uni-app 5.26 或以上；已验证版本为 5.26，较早版本未验证。详情见插件内 VALIDATION.md。

安装与运行

1. 用 HBuilderX 打开 qingyu-core，将 manifest.json 的 appid 替换为自己的 DCloud AppID。
2. 使用传统 uni-app / Vue 3 的 Android 运行目标，安装 HBuilderX 要求的 UTS Android 编译插件。不要使用 Web 运行验证 Core。
3. 先配置原生依赖运行环境：本机 HBuilderX 标准基座实测缺少 EXIF 编译类路径，需在「设置 → 运行配置」配置 Android 本地原生工程，或按当前 HBuilderX 提示制作包含 config.json 依赖的自定义基座。仅选择标准基座会报 找不到名称“exifinterface”。
4. 连接并授权 Android 真机，选择「运行 → 运行到手机或模拟器 → Android」，使用已配置的运行环境/自定义基座。
5. 页面选图，查看原图大小，设置目标 KiB 和最大宽高，开始压缩，检查耗时、预览、尺寸与达标状态。点击结果图放大查看，或点击“保存到相册”。保存失败时按页面提示检查相册权限。
6. 接入现有项目时，把整个 uni_modules/qingyu-imagecompress 复制到项目的 uni_modules/，从插件根目录导入。插件包含 UTS + Kotlin 原生混编文件，不能只复制 index.uts。

AndroidX EXIF 唯一显式依赖为 androidx.exifinterface:exifinterface:1.3.6（Apache-2.0），在 config.json 声明，首次构建需要能访问构建依赖仓库；不手动额外塞入同名 JAR/AAR。插件运行期间无网络请求、无统计 SDK、不申请权限；选图与源文件授权由应用处理。

完整调用（传统 uni-app JS）

// 传统 uni-app 使用 APP-PLUS 编译分支，并在运行时检查 Android。
// #ifdef APP-PLUS
import { compressImage } from '@/uni_modules/qingyu-imagecompress'

if (uni.getSystemInfoSync().platform !== 'android') {
  throw new Error('轻羽 Core 仅支持 Android')
}
uni.chooseImage({
  count: 1,
  sizeType: ['original'],
  sourceType: ['album'],
  success(selection) {
    compressImage({
      inputPath: selection.tempFilePaths[0],
      maxBytes: 200 * 1024,
      maxWidth: 2048,
      maxHeight: 2048,
      success(result) {
        console.log(result.outputPath, result.sizeBytes, result.width, result.height)
        if (!result.reachedTarget) {
          uni.showToast({ title: '未达到目标，请提高体积上限', icon: 'none' })
          return
        }
        // 此时可将 result.outputPath 用于预览/上传。
      },
      fail(error) {
        uni.showToast({ title: `${error.errCode}: ${error.errMsg}`, icon: 'none' })
      },
      complete() {
        // 关闭 loading。success / fail 完成后调用一次。
      }
    })
  }
})
// #endif

异步回调接口立即返回 void，不能直接 await compressImage()。需要 Promise 时由 JS 调用方包装：

const compress = options => new Promise((resolve, reject) => {
  compressImage({ ...options, success: resolve, fail: reject })
})
const result = await compress({ inputPath: localPath, maxBytes: 200 * 1024 })
// reachedTarget:false 仍然是有效处理结果，不会 reject。

UTS 调用方也使用 compressImage({ inputPath, maxBytes, success, fail, complete })。类型定义以 utssdk/interface.uts 为准；没有将未验收的 uni-app x 示例列为已兼容工程。

参数与返回值

路径与资源限制

• 接受本地绝对路径、file:// URI；适配 _doc/、_downloads/，通过 UTSAndroid.convert2AbsFullPath 转换。
• 不接受网络 URL、content://、普通相对路径、打包静态资源或 base64。系统选择器若返回 content URI，调用方先复制到应用本地临时文件。
• 输入文件最多 50 MiB，最多 1 亿像素，单边最多 32768 px。以解码识别的 MIME 判断 JPEG/PNG，不能靠改后缀转换格式。
• 预解码尺寸，按二次幂采样到不超过约 400 万像素；可用内存不足仍返回错误。方向修正后保持宽高比，不放大原图，极端长宽比按至少 1 px 舍入。
• JPEG 质量依次 90、75、60、45、30，优先保留较高分辨率。未达标时等比缩小，每轮比例最多 0.75（目标很小时可缩得更小）。最多 9 轮、45 次编码；长边最低 256 px，原图/调用尺寸本来小于 256 时不放大。
• 限制内未达标返回最小候选，reachedTarget:false。极小目标（例如 1 byte）不保证达标。
• IO dispatcher 后台执行，原生压缩串行化，主 dispatcher 回调。多个调用不会同时持有多套压缩位图；调用方应避免无界排队。

缓存与清理

输出位于应用 cacheDir/qingyu-imagecompress/qingyu-<UUID>.jpg。每次调用进入写入阶段时，只清理此目录中命名匹配的、超过 24 小时的插件输出，并跳过当前输入。未成功写完的输出会删除。系统可能随时回收缓存；需要长期保存时由调用方复制到持久目录。没有独立批量/清理 API。

错误

请按错误码处理，errMsg 用于提示。调用方必须传入接口定义要求的字段和类型；JS 跨语言桥接层对缺失字段/错误类型的异常不属于原生压缩流程。

验收与反馈

见插件内 验收记录。已完成原生编译、策略测试、UTS 转译、桥接联编、Android 16 原生模拟器测试，以及 vivo V2454A 上的传统 uni-app / Vue 3 真机功能测试。最低 Android 版本、其他真机、干净工程和市场下载包尚未单独验收。

反馈方式：通过插件详情页的 DCloud 私信联系作者。反馈时提供 HBuilderX/框架/Vue/Android 版本、参数、错误码与可脱敏复现图片。

官方参考：UTS 插件、原生混编、Android 开发。

启动时提示 plus is not defined

若自定义基座安装成功后，在页面启动前出现此错误，先核对 HBuilderX 与自定义基座版本，再重新安装现有自定义基座并重新同步项目资源。HBuilderX 若提示基座已是最新版本并跳过安装，需要重新触发基座安装，而不仅是重启应用。不要给 plus 添加空对象来绕过运行时初始化。

2026-10-13 在 vivo V2454A 上，对同一份自定义基座 APK 重新安装、同步并切回原项目后，应用启动和 plus 初始化恢复正常；具体复核范围见 验收记录。如仍报错，请提供启动完整日志，继续检查基座和运行时。