更新记录

1.0.2（2026-03-11）

修改文档

1.0.1（2026-03-11）

修改文档

1.0.0（2026-03-11）

首次上传

平台兼容性

云端兼容性

云函数类插件通用教程

使用云函数类插件的前提是：使用HBuilderX 2.9+

图片压缩服务 API 文档

🚨 重要提示

请您先试用再购买！
在正式购买前，请务必点击页面上的 "导入插件并试用" 按钮进行充分测试。
本插件由开发者利用业余时间开发维护，可能存在以下情况：

• 功能兼容性：请确认插件完全满足您的项目需求
• 问题响应：Bug修复可能无法做到即时响应
• 支持限制：优先处理已确认购买的正式用户问题

强烈建议：在试用环境中全面测试后，确认功能满足需求再进行购买！
感谢您的理解与支持 🙏

兼容性说明

本云对象服务全面兼容以下平台和框架：

方法列表

1. 单图压缩

方法名
compress(params)

请求参数

注意：url、base64、buffer 三个参数必须且只能选择一个传入。

返回结果

{
  code: Number,        // 200=成功
  message: String,     // 结果描述
  success: Boolean,    // 成功标识
  timestamp: Number,   // 时间戳
  data: {
    originalSize: Number,      // 原始大小（字节）
    compressedSize: Number,    // 压缩后大小（字节）
    width: Number,             // 压缩后宽度
    height: Number,            // 压缩后高度
    quality: Number,           // 压缩质量
    format: String,            // 图片格式（jpeg/png）
    base64: String,            // 压缩后的Base64数据
    buffer: Buffer,            // 压缩后的Buffer数据
    compressionRatio: Number,  // 压缩率（%）
    tip: String                // 提示信息
  }
}

2. 批量压缩

方法名
batchCompress(params)

请求参数

限制：单次最多处理10张图片，超出将拒绝处理。

返回结果

{
  code: Number,        // 200=成功
  message: String,     // 结果描述
  success: Boolean,    // 成功标识
  timestamp: Number,   // 时间戳
  data: {
    total: Number,        // 总数量
    successCount: Number, // 成功数量
    failCount: Number,    // 失败数量
    results: Array        // 每张图片的处理结果
  }
}

方法调用示例

示例1：通过URL压缩图片

const imageCompressor = uniCloud.importObject('image-compressor')

const res = await imageCompressor.compress({
  url: 'https://example.com/image.jpg',
  width: 800,
  quality: 80
})

if (res.success) {
  console.log('压缩成功，压缩率:', res.data.compressionRatio, '%')
  console.log('压缩后base64:', res.data.base64)
}

示例2：通过Base64压缩图片

const imageCompressor = uniCloud.importObject('image-compressor')

const res = await imageCompressor.compress({
  base64: 'data:image/jpeg;base64,/9j/4AAQ...',
  width: 600,
  height: 400,
  quality: 70
})

if (res.success) {
  console.log('原始大小:', res.data.originalSize, '字节')
  console.log('压缩后大小:', res.data.compressedSize, '字节')
}

示例3：仅调整质量，不改变尺寸

const imageCompressor = uniCloud.importObject('image-compressor')

const res = await imageCompressor.compress({
  url: 'https://example.com/image.png',
  quality: 60  // 只降低质量到60%
})

if (res.success) {
  console.log('质量调整完成')
}

示例4：批量压缩多张图片

const imageCompressor = uniCloud.importObject('image-compressor')

const res = await imageCompressor.batchCompress({
  images: [
    { url: 'https://example.com/img1.jpg', width: 800, quality: 80 },
    { base64: 'data:image/jpeg;base64,/9j/4AAQ...', quality: 70 },
    { url: 'https://example.com/img2.png', quality: 75 }
  ]
})

if (res.success) {
  console.log('批量处理完成')
  console.log('成功:', res.data.successCount, '张')
  console.log('失败:', res.data.failCount, '张')
}

关键特性说明

1. 尺寸智能处理

• 宽高比保持：指定宽度或高度时，另一边自动按比例计算
• 尺寸限制：最大支持20000像素，防止内存溢出
• 无参数模式：不指定宽高时，保持原始尺寸

处理规则：

• 仅指定 width：按比例计算 height
• 仅指定 height：按比例计算 width

2. 图片格式支持

• 输入格式：JPEG、PNG
• 输出格式：JPEG、PNG
• 格式转换：
  • JPEG输入 → JPEG输出
  • PNG输入 → PNG输出

3. 质量参数说明

• 范围：1-100，整数
• 默认值：70
• 推荐值：
  • Web图片：70-80
  • 缩略图：60-70
  • 高质量图片：85-95
• PNG格式：质量参数对PNG无效，PNG为无损格式

4. 批量处理限制

• 数量限制：单次最多10张图片
• 并发处理：所有图片同时压缩，提高效率
• 结果返回：包含每张图片的独立结果和统计信息
• 错误隔离：单张图片失败不影响其他图片处理

5. 性能优化建议

• 图片大小：建议单张图片不超过5MB
• 质量选择：根据使用场景选择合适质量值
• URL方式：确保图片服务器支持CORS
• 缓存策略：相同参数可缓存结果，减少重复计算

6. 错误处理与容错

• 下载重试：图片下载失败自动重试3次
• 边界检查：所有参数自动修正到合法范围

错误码说明

常见问题（FAQ）

Q：支持哪些图片格式？
A：目前支持JPEG、PNG两种格式。

Q：图片压缩超时？
A：原始图片越大所需要的压缩时间越长；请自行配置云对象的超时时间、函数执行内存等；

Q：图片太大导致处理失败怎么办？
A：建议前端先进行初步压缩，或者分多次处理。

Q：不同平台的超时限制不同如何处理？
A：服务会自动检测当前平台，建议根据平台特性调整批量处理的数量。

Q：数据太大云对象有限制？
A：云对象的接收参数的体积上限，支付宝云接收参数大小不可超过6MB，阿里云接收参数大小不可超过2MB，腾讯云接收参数大小不可超过5MB，由于传输层还有上下文环境信息，所以开发者给云对象发送参数时需注意控制参数体积。

Q：Base64格式如何传递？
A：支持纯base64字符串和data URL格式（如data:image/jpeg;base64,...）。

Q：质量参数对PNG格式有效吗？
A：PNG是无损格式，质量参数对其无效。建议需要压缩的场景使用JPEG格式。

Q：批量处理时部分图片失败会影响其他图片吗？
A：不会。批量处理时每张图片独立处理，单张失败不影响其他图片，结果中会明确标示每张图片的成功/失败状态。

Q：压缩后的图片可以直接上传到云存储吗？
A：服务返回的是Base64，需要前端自行调用uniCloud.uploadFile上传到云存储。

Q：如何判断压缩效果？
A：返回结果中包含compressionRatio字段，表示压缩率。同时可以对比originalSize和compressedSize字段。