云存储

uploadFile

1. 接口描述

接口功能：上传文件

接口声明：

2.x 版本

uploadFile(options)

1.x 版本

uploadFile(localPath: string, cloudPath: string)

注意事项: v2.x 与 v1.x 不兼容

2. 输入参数

字段	必填	类型	说明
localPath	是	String	本地文件路径，建议传入绝对路径
cloudPath	是	String	云端文件路径：`dir/data.txt`
onProgress	是	Function	上传进度回调函数

注：当 localPath 为文件夹时，SDK 会尝试在此文件夹下（一级目录，不深度遍历）寻找和 cloudPath 中所存在文件同名的文件，如 cloudPath 为 dir/data.txt，则会寻找 'data.txt'。

3. 返回结果

无

4. 示例代码

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  await storage.uploadFile({
    localPath: path.resolve("./data.txt"),
    cloudPath: "files/data.txt",
    onProgress: (data) => {},
  });
}

test();

uploadDirectory

1. 接口描述

接口功能：上传文件夹

接口声明：

2.x 版本

uploadDirectory(options)

1.x 版本

uploadDirectory(source: string, cloudPath: string)

注意事项: v2.x 与 v1.x 不兼容

此接口会遍历目标文件夹下所有的文件并上传，同时保持文件夹结构。

2. 输入参数

字段	必填	类型	说明
localPath	是	String	本地文件夹路径
cloudPath	是	String	云端文件夹路径
onProgress	是	Function	上传进度回调函数

3. 返回结果

无

4. 示例代码

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  await storage.uploadDirectory({
    localPath: path.resolve("./files"),
    cloudPath: "",
    onProgress: (data) => {},
  });
}

test();

downloadFile

1. 接口描述

接口功能：下载文件

接口声明：

2.x 版本

downloadFile(options)

1.x 版本

downloadFile(cloudPath: string, localPath)

注意事项: v2.x 与 v1.x 不兼容

2. 输入参数

字段	必填	类型	说明
cloudPath	是	String	云端文件路径：`dir/data.txt`
localPath	是	String	本地文件存储路径，文件需指定文件名称

3. 返回结果

无(undefined)

4. 示例代码

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  await storage.downloadFile({
    cloudPath: "files/data.txt",
    localPath: path.resolve("./data.txt"),
  });
}

test();

downloadDirectory

1. 接口描述

接口功能：下载文件夹

接口声明：

2.x 版本

downloadDirectory(options)

1.x 版本

downloadDirectory(cloudPath: string, localPath: string)

注意事项: v2.x 与 v1.x 不兼容

2. 输入参数

字段	必填	类型	说明
cloudPath	是	String	云端文件夹
localPath	是	String	本地文件存储路径，文件需指定文件名称

3. 返回结果

无

4. 示例代码

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  await storage.downloadDirectory({
    cloudPath: "files/music",
    localPath: path.resolve("./music"),
  });
}

test();

NOTE：

此操作会遍历文件夹下的所有文件，如果文件数量过多，可能会造成执行失败。
当 cloudPath 不存在时，SDK 不会下载文件，也不会抛出错误。

listDirectoryFiles

1. 接口描述

接口功能：列出文件夹下的所有文件

接口声明：listDirectoryFiles(cloudPath: string): Promise<IListFileInfo[]>

2. 输入参数

字段	必填	类型	说明
cloudPath	是	String	云端文件夹路径：`dir/data/`

3. 返回结果

字段	必填	类型	说明
-	是	`Array<FileItem>`	文件数组

FileItem

字段	类型	说明
Key	String	对象键
LastModified	String	对象最后修改时间，为 ISO8601 格式，如 2019-05-24T10:56:40Z date
ETag	String	对象的实体标签（Entity Tag），是对象被创建时标识对象内容的信息标签，可用于检查对象的内容是否发生变化
Size	String	对象大小，单位为 Byte
Owner	String	对象持有者信息
StorageClass	String	对象存储类型，标准存储 STANDARD

4. 示例代码

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  const res1 = await storage.listDirectoryFiles("dir/data");

  const res2 = await storage.listDirectoryFiles("dir/data", 20);

  const res3 = await storage.listDirectoryFiles("dir/data", 20, "dir/dat");

  for (let item in res1) {
    console.log(item);
  }
}
test();

getFileInfo

1. 接口描述

接口功能：获取文件信息

接口声明：getFileInfo(cloudPath: string): Promise<IFileInfo>

2. 输入参数

字段	必填	类型	说明
cloudPath	是	String	云端文件路径 `dir/data.txt`

3. 返回结果

字段	必填	类型	说明
Size	是	String	文件大小 KB
Type	是	String	文件类型
Date	是	String	修改时间
ETag	是	String	对象的实体标签（Entity Tag）

4. 示例代码

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  const info = await storage.getFileInfo("files/data.txt");
  console.log(info);
}

test();

deleteFile

1. 接口描述

接口功能：批量删除文件

接口声明：deleteFile(cloudPathList: string[])

2. 输入参数

字段	必填	类型	说明
cloudPathList	是	`Array<String>`	云端文件路径组成的字符串数组 `['dir/data.txt']`

3. 返回结果

无

4. 示例代码

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  await storage.deleteFile(["files/data.txt"]);
}

test();

deleteDirectory

1. 接口描述

接口功能：删除文件夹

接口声明：deleteDirectory(cloudPath: string)

2. 输入参数

字段	必填	类型	说明
cloudPath	是	String	云端文件夹路径

注意： 当 cloudPath 不存在时，SDK 不会抛出错误。

3. 返回结果

无

4. 示例代码

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  await storage.deleteDirectory("files/");
}

test();

getTemporaryUrl

1. 接口描述

接口功能：获取文件临时下载链接

接口声明：getTemporaryUrl(fileList: (string | TempUrlInfo)[]):Promise<Array.<FileUrlItem>>

2. 输入参数

字段	必填	类型	说明
fileList	是	`String` 或 `Array.<TempUrlInfo>`	云端文件路径数组或 TempUrlInfo 数组

TempUrlInfo

字段	必填	类型	说明
cloudPath	是	String	云端文件路径
maxAge	是	Number	临时下载链接有效时间，单位：秒

3. 返回结果

字段	必填	类型	说明
-	是	`Array.<FileUrlItem>`	文件下载链接列表

FileUrlItem

字段	必填	类型	说明
fileId	是	String	文件 Id
url	是	String	下载链接

4. 示例代码

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  const urls = await storage.getTemporaryUrl(["files/data.txt"]);

  const urls2 = await storage.getTemporaryUrl([
    {
      cloudPath: "files/data.txt",
      maxAge: 86400,
    },
  ]);

  for (let item in urls) {
    console.log(item.url);
  }
}

test();

getStorageAcl

1. 接口描述

接口功能：获取文件存储权限

接口声明：getStorageAcl(): Promise<string>

2. 输入参数

空

3. 返回结果

字段	必填	类型	说明
-	是	String	权限类型

所有权限类型：

READONLY：所有用户可读，仅创建者和管理员可写
PRIVATE：仅创建者及管理员可读写
ADMINWRITE：所有用户可读，仅管理员可写
ADMINONLY：仅管理员可读写

4. 示例代码

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  const acl = await storage.getStorageAcl();
  console.log(acl);
}

test();

setStorageAcl

1. 接口描述

接口功能：设置文件存储权限

接口声明：setStorageAcl(acl: string):Promise<Object>

2. 输入参数

字段	必填	类型	说明
acl	是	`String`	文件存储权限描述

acl 支持选项：

READONLY：所有用户可读，仅创建者和管理员可写
PRIVATE：仅创建者及管理员可读写
ADMINWRITE：所有用户可读，仅管理员可写
ADMINONLY：仅管理员可读写

3. 返回结果

字段	必填	类型	说明
RequestId	是	String	请求 ID

4. 示例代码

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  await storage.setStorageAcl("READONLY");
}

test();

listCurrentDirectory

1. 接口描述

接口功能：列出指定目录下的文件和子目录（非递归，仅当前层级）

接口声明：app.storage.listCurrentDirectory(dirPath?: string): Promise<Object>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
dirPath	否	String	云端目录路径，不传则列出根目录；路径末尾无需加 `/`

3. 返回结果

字段	类型	说明
files	IListFileInfo[]	当前层级的文件列表
directories	String[]	当前层级的子目录名列表

4. 示例代码

const CloudBase = require('@cloudbase/manager-node')
const app = new CloudBase({ secretId: 'Your SecretId', secretKey: 'Your SecretKey', envId: 'your-env-id' })

async function test() {
  const { files, directories } = await app.storage.listCurrentDirectory('images')
  console.log('文件:', files)
  console.log('子目录:', directories)
}

test()

copyFile

1. 接口描述

接口功能：将云端单个文件复制到新路径

接口声明：app.storage.copyFile(options: ICopyOptions): Promise<ICopyResult>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

ICopyOptions

字段	必填	类型	说明
sourcePath	是	String	源文件云端路径，例如 `images/a.jpg`
destPath	是	String	目标文件云端路径，例如 `backup/a.jpg`
force	否	Boolean	是否强制覆盖已存在的目标文件，默认 `false`
skipExisting	否	Boolean	目标已存在时跳过（不报错），默认 `false`

3. 返回结果

ICopyResult

字段	类型	说明
success	Boolean	是否成功
sourcePath	String	源路径
destPath	String	目标路径
size	Number	文件大小（bytes）
status	String	状态：`copied` / `skipped` / `failed`
error	String	失败时的错误信息

4. 示例代码

async function test() {
  const result = await app.storage.copyFile({
    sourcePath: 'images/logo.png',
    destPath: 'backup/logo.png',
    force: true
  })
  console.log('复制结果:', result)
}

test()

copyDirectory

1. 接口描述

接口功能：将云端目录递归复制到新路径，支持 glob 过滤和并发控制

接口声明：app.storage.copyDirectory(options: ICopyDirectoryOptions): Promise<ICopyResult[]>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

ICopyDirectoryOptions（继承 ICopyOptions）

字段	必填	类型	说明
sourcePath	是	String	源目录云端路径
destPath	是	String	目标目录云端路径
force	否	Boolean	是否强制覆盖已存在的文件，默认 `false`
skipExisting	否	Boolean	目标已存在时跳过，默认 `false`
include	否	String \| String[]	包含模式（glob 格式）
exclude	否	String \| String[]	排除模式（glob 格式）
parallel	否	Number	并发数，默认 `20`
onProgress	否	Function	进度回调 `(info: ICopyProgress) => void`

ICopyProgress

字段	类型	说明
copied	Number	已复制数量
skipped	Number	已跳过数量
total	Number	总文件数
currentFile	String	当前正在处理的文件

3. 返回结果

Promise<ICopyResult[]> — 每个文件的复制结果数组，结构同 copyFile 返回值。

4. 示例代码

async function test() {
  const results = await app.storage.copyDirectory({
    sourcePath: 'src-dir/',
    destPath: 'dest-dir/',
    include: ['**/*.jpg', '**/*.png'],
    force: true,
    onProgress: ({ copied, total }) => console.log(`${copied}/${total}`)
  })
  console.log('目录复制完成，共', results.length, '个文件')
}

test()

moveFile

1. 接口描述

接口功能：将云端单个文件移动（复制后删除源文件）到新路径

接口声明：app.storage.moveFile(options: ICopyOptions): Promise<ICopyResult>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

同 copyFile，参数结构完全一致。

ICopyOptions

字段	必填	类型	说明
sourcePath	是	String	源文件云端路径
destPath	是	String	目标文件云端路径
force	否	Boolean	是否强制覆盖已存在的目标文件，默认 `false`
skipExisting	否	Boolean	目标已存在时跳过，默认 `false`

3. 返回结果

同 copyFile，返回 ICopyResult。

4. 示例代码

async function test() {
  const result = await app.storage.moveFile({
    sourcePath: 'temp/upload.jpg',
    destPath: 'images/upload.jpg',
    force: true
  })
  console.log('移动结果:', result.status)
}

test()

moveDirectory

1. 接口描述

接口功能：将云端目录递归移动（复制后删除源目录）到新路径

接口声明：app.storage.moveDirectory(options: ICopyDirectoryOptions): Promise<ICopyResult[]>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

同 copyDirectory，参数结构完全一致。

3. 返回结果

同 copyDirectory，返回 ICopyResult[]。

4. 示例代码

async function test() {
  const results = await app.storage.moveDirectory({
    sourcePath: 'old-dir/',
    destPath: 'new-dir/',
    force: true
  })
  console.log('目录移动完成，共', results.length, '个文件')
}

test()

searchFiles

1. 接口描述

接口功能：在指定目录下按 glob 模式或正则表达式搜索文件

接口声明：app.storage.searchFiles(options: ISearchOptions): Promise<ISearchResult[]>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

ISearchOptions

字段	必填	类型	说明
pattern	是	String	搜索模式，支持 glob 或正则表达式字符串
path	否	String	搜索目录路径，不指定则搜索根目录
isRegex	否	Boolean	`true` 时将 `pattern` 解析为正则表达式，默认 `false`
fileType	否	String	文件类型过滤，例如 `jpg`、`png`
limit	否	Number	返回结果数量上限，默认 `100`
includeDetails	否	Boolean	是否包含文件大小和修改时间，默认 `false`

3. 返回结果

ISearchResult[]

字段	类型	说明
key	String	文件云端路径
type	String	类型：`file` / `directory`
size	Number	文件大小（bytes），仅文件有效
lastModified	String	最后修改时间（ISO 格式），仅文件有效

4. 示例代码

async function test() {
  const results = await app.storage.searchFiles({
    pattern: '**/*.jpg',
    path: 'images',
    limit: 50,
    includeDetails: true
  })
  results.forEach(f => console.log(f.key, f.size))
}

test()

云存储

uploadFile​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

uploadDirectory​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

downloadFile​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

downloadDirectory​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

listDirectoryFiles​

1. 接口描述​

2. 输入参数​

3. 返回结果​

FileItem​

4. 示例代码​

getFileInfo​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

deleteFile​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

deleteDirectory​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

getTemporaryUrl​

1. 接口描述​

2. 输入参数​

TempUrlInfo​

3. 返回结果​

FileUrlItem​

4. 示例代码​

getStorageAcl​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

setStorageAcl​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

listCurrentDirectory​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

copyFile​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

copyDirectory​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

moveFile​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

moveDirectory​

uploadFile

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

uploadDirectory

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

downloadFile

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

downloadDirectory

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

listDirectoryFiles

1. 接口描述

2. 输入参数

3. 返回结果

FileItem

4. 示例代码

getFileInfo

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

deleteFile

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

deleteDirectory

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

getTemporaryUrl

1. 接口描述

2. 输入参数

TempUrlInfo

3. 返回结果

FileUrlItem

4. 示例代码

getStorageAcl

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

setStorageAcl

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

listCurrentDirectory

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

copyFile

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

copyDirectory

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

moveFile

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

moveDirectory

1. 接口描述