云调用扩展

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

处理方式

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

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

Web 端
微信小程序
Node.js

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

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

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

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

需要将图片处理域名 *.pic.ap-shanghai.myqcloud.com 添加到小程序的 request 合法域名列表中

配置路径：微信公众平台 > 开发 > 开发管理 > 开发设置 > 服务器域名

代码示例

Web 端
微信小程序
Node.js

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;
  }
}

import extCi from '@cloudbase/extension-ci-wxmp';

// 初始化云开发
wx.cloud.init({
  env: 'your-env-id'
});

// 注册扩展
wx.cloud.registerExtension(extCi);

// 处理图片
async function processImage() {
  try {
    // 选择图片
    const { tempFilePaths } = await wx.chooseImage({
      count: 1,
      sizeType: ['original']
    });
    
    // 上传文件到云存储
    const uploadResult = await wx.cloud.uploadFile({
      cloudPath: `temp/${Date.now()}.jpg`,
      filePath: tempFilePaths[0]
    });
    
    // 调用图像处理扩展
    const result = await wx.cloud.invokeExtension('CloudInfinite', {
      action: 'ImageProcess',                    // 操作类型
      cloudPath: uploadResult.fileID,            // 源文件 ID
      operations: {
        rules: [
          {
            fileid: '/processed/demo.png',       // 输出文件路径
            rule: 'imageMogr2/format/png|imageMogr2/thumbnail/!50p'  // 转 PNG 并缩放
          }
        ]
      }
    });
    
    console.log('处理结果:', result);
    return result;
  } catch (err) {
    console.error('图像处理失败:', err);
    wx.showToast({
      title: '处理失败',
      icon: 'none'
    });
  }
}

const tcb = require('@cloudbase/node-sdk');
const extCi = require('@cloudbase/extension-ci');
const fs = require('fs');

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

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

// 处理图片
async function processImage() {
  try {
    // 读取本地文件
    const fileContent = fs.readFileSync('./demo.jpg');
    
    // 调用图像处理扩展
    const result = await app.invokeExtension('CloudInfinite', {
      action: 'ImageProcess',                    // 操作类型
      cloudPath: 'demo.jpg',                     // 源文件路径
      fileContent: fileContent,                  // 文件内容
      operations: {
        rules: [
          {
            fileid: '/processed/demo.png',       // 输出文件路径
            rule: 'imageMogr2/format/png'        // 处理规则
          }
        ]
      }
    });
    
    console.log('处理结果:', result);
    return result;
  } catch (err) {
    console.error('图像处理失败:', err);
    throw err;
  }
}

// 执行处理
processImage();

参数说明

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

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;
  }
}

处理方式​

方式一：URL 拼接参数​

使用方法​

常用处理参数​

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

安装扩展 SDK​

代码示例​

参数说明​

常见错误处理​

相关文档​