跳到主要内容

云调用扩展

云存储可以与云开发提供的云调用扩展服务联动，提供「存储+处理」一体化解决方案。您可以根据实际需求安装相应的扩展能力，实现图像处理、图像标签识别、图像盲水印、图像安全审核等功能。

处理方式​

云开发提供两种图片处理方式：

  • URL 拼接参数：适用于单次处理，直接在图片 URL 后拼接处理参数
  • 持久化处理：适用于批量处理或需要保存处理结果的场景，使用 SDK 进行处理

方式一：URL 拼接参数​

此方式适用于单次图片处理，无需安装 SDK，直接在图片 URL 后拼接处理参数即可。处理后的链接可在小程序、Web 网页中使用，也可用于图床。

使用方法​

在云存储图片的下载地址或临时链接后，使用 & 符号拼接处理参数。

示例：将图片等比例缩小到原来的 20%

// 原始图片地址
https://786c-xly-xrlur-1300446086.tcb.qcloud.la/hehe.jpg?sign=b8ac757538940ead8eed4786449b4cd7&t=1591752049

// 拼接缩放参数后
https://786c-xly-xrlur-1300446086.tcb.qcloud.la/hehe.jpg?sign=b8ac757538940ead8eed4786449b4cd7&t=1591752049&imageMogr2/thumbnail/!20p

常用处理参数​

const downloadUrl = "https://786c-xly-xrlur-1300446086.tcb.qcloud.la/hehe.jpg?sign=xxx&t=xxx";

// 等比缩放
downloadUrl + "&imageMogr2/thumbnail/!20p"           // 缩放到原图的 20%
downloadUrl + "&imageMogr2/thumbnail/!50px"          // 宽度缩放到 50%，高度不变
downloadUrl + "&imageMogr2/thumbnail/!x50p"          // 高度缩放到 50%，宽度不变

// 指定尺寸
downloadUrl + "&imageMogr2/thumbnail/640x"           // 宽度 640px，高度等比缩放
downloadUrl + "&imageMogr2/thumbnail/x355"           // 高度 355px，宽度等比缩放
downloadUrl + "&imageMogr2/thumbnail/640x355"        // 限定最大宽高，等比缩放
downloadUrl + "&imageMogr2/thumbnail/640x355r"       // 限定最小宽高，等比缩放
downloadUrl + "&imageMogr2/thumbnail/640x355!"       // 强制缩放到指定尺寸（可能变形）
downloadUrl + "&imageMogr2/thumbnail/150000@"        // 限制总像素数不超过 150000

// 裁剪效果
downloadUrl + "&imageMogr2/iradius/300"              // 内切圆裁剪，半径 300px
downloadUrl + "&imageMogr2/rradius/100"              // 圆角裁剪，半径 100px

// 其他效果
downloadUrl + "&imageMogr2/rotate/90"                // 顺时针旋转 90 度
downloadUrl + "&imageMogr2/format/png"               // 转换为 PNG 格式
downloadUrl + "&imageMogr2/blur/8x5"                 // 高斯模糊（半径 8，sigma 5）

// 获取图片信息
downloadUrl + "&imageInfo"                           // 返回图片基础信息（JSON 格式）

💡 提示：

  • 参数中 p 表示百分比，x 表示像素值
  • 多个处理参数可以叠加使用，用 | 符号分隔
  • 更多参数说明请参考 图像处理文档

方式二：持久化图像处理​

此方式适用于需要批量处理或保存处理结果的场景，通过 SDK 调用云调用扩展能力。

安装扩展 SDK​

npm install --save @cloudbase/extension-ci@latest

⚠️ 微信小程序注意事项：

  • 需要将图片处理域名 *.pic.ap-shanghai.myqcloud.com 添加到小程序的 request 合法域名列表中
  • 配置路径：微信公众平台 > 开发 > 开发管理 > 开发设置 > 服务器域名

代码示例​

import tcb from 'tcb-js-sdk';
import extCi from '@cloudbase/extension-ci';

// 初始化 SDK
const app = tcb.init({
  env: 'your-env-id'
});

// 注册扩展
tcb.registerExtension(extCi);

// 读取文件内容
const readFile = (file) => {
  return new Promise((resolve) => {
    const reader = new FileReader();
    reader.onload = (e) => {
      const arrayBuffer = new Uint8Array(e.target.result);
      resolve(arrayBuffer);
    };
    reader.readAsArrayBuffer(file);
  });
};

// 处理图片
async function processImage() {
  try {
    // 获取用户选择的文件
    const file = document.getElementById('selectFile').files[0];
    const fileContent = await readFile(file);
    
    // 调用图像处理扩展
    const result = await app.invokeExtension('CloudInfinite', {
      action: 'ImageProcess',                    // 操作类型：ImageProcess
      cloudPath: 'processed/demo.png',           // 处理后保存的路径
      fileContent: fileContent,                  // 文件内容
      operations: {
        rules: [
          {
            fileid: '/processed/demo.png',       // 输出文件路径
            rule: 'imageMogr2/format/png'        // 处理规则：转换为 PNG
          }
        ]
      }
    });
    
    console.log('处理结果:', result);
    return result;
  } catch (err) {
    console.error('图像处理失败:', err);
    throw err;
  }
}

参数说明​

参数类型必填说明
actionString是操作类型。可选值：
- ImageProcess：图像处理
- DetectType：图片安全审核
- WaterMark：图片盲水印
- DetectLabel：图像标签识别
cloudPathString是云存储中的文件路径或文件 ID
fileContentBuffer/Uint8Array否文件内容（上传新文件时需要）
operationsObject是处理参数，具体格式见下方说明

operations 对象结构：

{
  rules: [
    {
      fileid: '/output/path.png',      // 输出文件路径
      rule: 'imageMogr2/format/png'    // 处理规则（与 URL 拼接参数相同）
    }
  ]
}

常见错误处理​

async function processImageWithErrorHandling() {
  try {
    const result = await app.invokeExtension('CloudInfinite', {
      // ... 参数配置
    });
    return result;
  } catch (err) {
    // 处理常见错误
    if (err.code === 'RESOURCE_NOT_FOUND') {
      console.error('源文件不存在，请检查 cloudPath 参数');
    } else if (err.code === 'PERMISSION_DENIED') {
      console.error('权限不足，请检查安全规则配置');
    } else if (err.code === 'EXTENSION_NOT_INSTALLED') {
      console.error('未安装图像处理扩展，请前往云开发平台安装');
    } else {
      console.error('图像处理失败:', err.message);
    }
    throw err;
  }
}

相关文档​