更新记录

1.0.4（2025-06-26）

移除非必要文件

1.0.3（2025-06-26）

1

1.0.2（2025-06-26）

移除非必要文件

平台兼容性

云函数类插件通用教程

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

图片压缩模块

基于 TinyPNG API 的图片压缩模块，支持在 uniCloud 云函数环境中使用。

功能特性

• 支持常见图片格式压缩（JPG、JPEG、PNG、WebP）
• 基于 TinyPNG API 进行高质量压缩
• 自动上传压缩后的图片到云存储
• 支持自定义文件名和存储路径
• 完整的错误处理机制

环境要求

• uniCloud 云函数环境
• TinyPNG API Key

依赖安装

# 项目根目录下运行命令
cd ./uni_modules/x-compress-image/uniCloud/cloudfunctions/common/x-compress-image
npm install tinify

配置说明

在 x-config-center 配置文件中添加 TinyPNG API Key：, 文件路径 uniCloud/cloudfunctions/common/x-config-center/index.js

{
  "tinify": {
    "key": "your-tinypng-api-key"
  }
}

使用方法

基本用法

const compressImage = require('./index.js');

// 压缩图片
const result = await compressImage(
  'https://example.com/image.jpg',  // 图片URL
  '/compressed/',                   // 云存储目录
  'compressed-image.jpg'            // 文件名（可选）
);

console.log(result);

参数说明

返回值

函数返回一个 Promise，解析为 CompressImageResult 对象：

interface CompressImageResult {
  errCode: string;    // "0" 表示成功，"1" 表示失败
  errMsg: string;     // 错误或成功消息
  fileID?: string;    // 压缩后图片的云存储地址（成功时返回）
  error?: string;     // 详细错误信息（失败时返回）
}

使用示例

示例 1：基础压缩

const compressImage = require('./index.js');

async function compressBasic() {
  const result = await compressImage(
    'https://example.com/photos/large-image.jpg',
    '/images/compressed/',
    'small-image.jpg'
  );

  if (result.errCode === '0') {
    console.log('压缩成功！');
    console.log('压缩后图片地址：', result.fileID);
  } else {
    console.error('压缩失败：', result.errMsg);
  }
}

示例 2：批量压缩

const compressImage = require('./index.js');

async function compressBatch(imageUrls) {
  const results = [];

  for (const imageUrl of imageUrls) {
    try {
      const result = await compressImage(
        imageUrl,
        '/batch-compressed/',
        // 不指定文件名，自动从URL提取
      );
      results.push(result);
    } catch (error) {
      console.error('压缩失败：', error);
    }
  }

  return results;
}

// 使用示例
const imageUrls = [
  'https://example.com/image1.jpg',
  'https://example.com/image2.png',
  'https://example.com/image3.webp'
];

compressBatch(imageUrls).then(results => {
  console.log('批量压缩结果：', results);
});

示例 3：错误处理

const compressImage = require('./index.js');

async function compressWithErrorHandling(imageUrl) {
  try {
    const result = await compressImage(imageUrl, '/uploads/');

    switch (result.errCode) {
      case '0':
        console.log('✅ 压缩成功');
        console.log('📁 文件地址：', result.fileID);
        break;
      case '1':
        console.error('❌ 压缩失败：', result.errMsg);
        if (result.error) {
          console.error('📋 详细错误：', result.error);
        }
        break;
      default:
        console.error('⚠️ 未知状态');
    }
  } catch (error) {
    console.error('💥 程序执行错误：', error);
  }
}

支持的图片格式

• .jpg / .jpeg
• .png
• .webp

错误码说明

常见错误

1. 缺少 imageUrl 参数

// 错误示例
const result = await compressImage('', '/path/');
// 返回：{ errCode: '1', errMsg: '缺少 imageUrl 参数' }

2. 不支持的图片格式

// 错误示例
const result = await compressImage('https://example.com/file.gif', '/path/');
// 返回：{ errCode: '1', errMsg: '不支持的图片格式' }

3. TinyPNG API 配置错误

确保在配置文件中正确设置了 TinyPNG API Key，并且 API Key 有效且未超出使用限制。

性能优化建议

1. 合理使用 API 配额：TinyPNG API 通常有月度压缩次数限制，请合理规划使用。

2. 缓存机制：对于相同的图片，建议实现缓存机制避免重复压缩。

3. 批量处理：对于大量图片压缩，建议控制并发数量避免超出 API 限制。

4. 错误重试：对于网络问题导致的失败，可以实现重试机制。

注意事项

• 确保 uniCloud 环境配置正确
• TinyPNG API Key 需要有效且有足够的配额
• 网络图片需要可访问
• 云存储路径需要有写入权限