云存储

uploadFile​

1. 接口描述​

接口功能：上传文件

接口声明：

2.x 版本

uploadFile(options)

1.x 版本

uploadFile(localPath: string, cloudPath: string)

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

2. 输入参数​

注：当 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. 输入参数​

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. 输入参数​

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. 输入参数​

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. 输入参数​

3. 返回结果​

FileItem​

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. 输入参数​

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() {
  const info = await storage.getFileInfo("files/data.txt");
  console.log(info);
}

test();

deleteFile​

1. 接口描述​

接口功能：批量删除文件

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

2. 输入参数​

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 不存在时，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. 输入参数​

TempUrlInfo​

3. 返回结果​

FileUrlItem​

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. 返回结果​

所有权限类型：

• 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 支持选项：

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

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.setStorageAcl("READONLY");
}

test();

listCurrentDirectory​

1. 接口描述​

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

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

2. 输入参数​

3. 返回结果​

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>

2. 输入参数​

ICopyOptions

3. 返回结果​

ICopyResult

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[]>

2. 输入参数​

ICopyDirectoryOptions（继承 ICopyOptions）

ICopyProgress

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>

2. 输入参数​

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

ICopyOptions

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[]>

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[]>

2. 输入参数​

ISearchOptions

3. 返回结果​

ISearchResult[]

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()

PostgreSQL 环境​

uploadObject​

1. 接口描述​

接口功能：通过 HTTP API 以 Binary 直传方式上传对象。

接口声明：app.storage.uploadObject(options): Promise<IUploadObjectHttpResult>

2. 输入参数​

IUploadObjectHttpOptions

约束：单文件大小上限为 100 MB，超出会抛 FileSizeLimitExceeded。

3. 返回结果​

IUploadObjectHttpResult

4. 示例代码​

const res = await app.storage.uploadObject({
  bucketId: 'my-bucket',
  objectName: 'images/avatar.png',
  localPath: './avatar.png',
  cacheControl: 3600,
  metadata: { source: 'manager-node' },
  upsert: true,
  accessToken: '<your-access-token>'
})
console.log(res.Id, res.Key)

deleteObject​

1. 接口描述​

接口功能：删除单个对象。

接口声明：app.storage.deleteObject(options): Promise<IDeleteObjectHttpResult>

2. 输入参数​

3. 返回结果​

deleteObjects​

1. 接口描述​

接口功能：批量删除对象，单次最多 20 个。

接口声明：app.storage.deleteObjects(options): Promise<IDeletedObjectInfo[]>

2. 输入参数​

3. 返回结果​

IDeletedObjectInfo[]，每项包含 name / bucket_id / owner_id 等字段；不存在的对象会被服务端静默跳过（不出现在返回数组中）。

4. 示例代码​

const deleted = await app.storage.deleteObjects({
  bucketId: 'my-bucket',
  prefixes: ['test/a.txt', 'test/b.txt'],
  accessToken: '<your-access-token>'
})
console.log(deleted.map(d => d.name))

copyObject​

1. 接口描述​

接口功能：复制对象。

接口声明：app.storage.copyObject(options): Promise<ICopyObjectHttpResult>

2. 输入参数​

3. 返回结果​

ICopyObjectHttpResult：包含 Id / Key / name / bucket_id / owner_id / version / created_at / updated_at / last_accessed_at / metadata / user_metadata 等字段。

moveObject​

1. 接口描述​

接口功能：移动对象，由服务端一次性完成「复制 + 删除源对象」。

接口声明：app.storage.moveObject(options): Promise<IMoveObjectHttpResult>

2. 输入参数​

3. 返回结果​

listObjects​

1. 接口描述​

接口功能：列出 bucket 下的对象，支持前缀过滤、分页与排序。

接口声明：app.storage.listObjects(options): Promise<IListObjectsHttpResult>

2. 输入参数​

3. 返回结果​

IListObjectsHttpResult

signObject​

1. 接口描述​

接口功能：为单个对象生成签名下载 URL。

接口声明：app.storage.signObject(options): Promise<ISignObjectHttpResult>

2. 输入参数​

3. 返回结果​

signObjects​

1. 接口描述​

接口功能：批量为多个对象生成签名下载 URL，单次最多 500 个。

接口声明：app.storage.signObjects(options): Promise<ISignObjectsHttpResult>

2. 输入参数​

3. 返回结果​

ISignedObjectItem[]

signUploadObject​

1. 接口描述​

接口功能：为对象生成签名上传 URL。

接口声明：app.storage.signUploadObject(options): Promise<ISignUploadObjectHttpResult>

2. 输入参数​

3. 返回结果​

uploadObjectBySign​

1. 接口描述​

接口功能：使用签名 URL 上传对象，无需 Authorization 头。

接口声明：app.storage.uploadObjectBySign(options): Promise<IUploadObjectBySignHttpResult>

2. 输入参数​

3. 返回结果​

downloadAuthenticatedObject​

1. 接口描述​

接口功能：下载需认证对象，始终携带 Authorization 头。

接口声明：app.storage.downloadAuthenticatedObject(options): Promise<IDownloadObjectHttpResult>

2. 输入参数​

3. 返回结果​

IDownloadObjectHttpResult

4. 示例代码​

import fs from 'fs'

const { status, body } = await app.storage.downloadAuthenticatedObject({
  bucketId: 'my-bucket',
  objectName: 'images/avatar.png',
  accessToken: '<your-access-token>'
})
if (body) body.pipe(fs.createWriteStream('./avatar.png'))

downloadObject​

1. 接口描述​

接口功能：下载对象，accessToken 可选；不传时仅 public bucket 可访问。

接口声明：app.storage.downloadObject(options): Promise<IDownloadObjectHttpResult>

2. 输入参数​

参数与 downloadAuthenticatedObject 相同，区别在于 accessToken 为可选。

3. 返回结果​

同 downloadAuthenticatedObject。

downloadPublicObject​

1. 接口描述​

接口功能：下载公开对象，无需认证；目标必须为 public bucket。

接口声明：app.storage.downloadPublicObject(options): Promise<IDownloadObjectHttpResult>

2. 输入参数​

3. 返回结果​

同 downloadAuthenticatedObject。

downloadObjectBySign​

1. 接口描述​

接口功能：使用签名 URL 下载对象，无需 Authorization。

接口声明：app.storage.downloadObjectBySign(options): Promise<IDownloadObjectHttpResult>

2. 输入参数​

3. 返回结果​

同 downloadAuthenticatedObject。

getObjectInfoAuthenticated​

1. 接口描述​

接口功能：获取对象元信息（需认证）。

接口声明：app.storage.getObjectInfoAuthenticated(options): Promise<IGetObjectInfoHttpResult>

2. 输入参数​

3. 返回结果​

IGetObjectInfoHttpResult

IObjectInfoHttpPayload：id / name / version / bucket_id / size / content_type / cache_control / etag / metadata / last_modified / created_at。

getObjectInfoPublic​

1. 接口描述​

接口功能：获取公开对象元信息，无需认证；目标必须为 public bucket。仅支持 GET。

接口声明：app.storage.getObjectInfoPublic(options): Promise<IGetObjectInfoHttpResult>

2. 输入参数​

3. 返回结果​

同 getObjectInfoAuthenticated，且 body 一定为 IObjectInfoHttpPayload。