跳到主要内容

云存储

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​

字段类型说明
KeyString对象键
LastModifiedString对象最后修改时间，为 ISO8601 格式，如 2019-05-24T10:56:40Z date
ETagString对象的实体标签（Entity Tag），是对象被创建时标识对象内容的信息标签，可用于检查对象的内容是否发生变化
SizeString对象大小，单位为 Byte
OwnerString对象持有者信息
StorageClassString对象存储类型，标准存储 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. 返回结果​

字段类型说明
filesIListFileInfo[]当前层级的文件列表
directoriesString[]当前层级的子目录名列表

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

字段类型说明
successBoolean是否成功
sourcePathString源路径
destPathString目标路径
sizeNumber文件大小（bytes）
statusString状态：copied / skipped / failed
errorString失败时的错误信息

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

字段类型说明
copiedNumber已复制数量
skippedNumber已跳过数量
totalNumber总文件数
currentFileString当前正在处理的文件

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否Booleantrue 时将 pattern 解析为正则表达式，默认 false
fileType否String文件类型过滤，例如 jpg、png
limit否Number返回结果数量上限，默认 100
includeDetails否Boolean是否包含文件大小和修改时间，默认 false

3. 返回结果​

ISearchResult[]

字段类型说明
keyString文件云端路径
typeString类型：file / directory
sizeNumber文件大小（bytes），仅文件有效
lastModifiedString最后修改时间（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()

PostgreSQL 环境​

版本提示

以下接口面向 PostgreSQL 架构 的云开发环境，基于 CloudBase Storage HTTP API 实现，自 @cloudbase/manager-node@5.4.0 起提供。

  • 与本页前面基于 COS SDK 的接口（uploadFile / downloadFile / listDirectoryFiles …）面向不同架构，不可混用。

  • 所有接口都需要传 accessToken（Bearer Token），可选值：

    • access_token：登录态访问令牌
    • apiKey：服务端管理员访问凭证（JWT，由 env.createApiKey 创建，长期有效）
    • publishableKey：前端匿名访问凭证

    ⚠️ apiKey 严禁在客户端使用。

  • 所有接口均支持可选的 envId 字段，用于覆盖当前环境 ID；不传时使用初始化时的 envId。

uploadObject​

1. 接口描述​

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

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

2. 输入参数​

IUploadObjectHttpOptions

字段必填类型说明
bucketId是StringBucket ID
objectName是String对象名，支持路径，例如 folder/file.png
localPath否String本地文件绝对/相对路径（与 body 二选一）
body否Buffer / NodeJS.ReadableStream文件内容（与 localPath 二选一）
contentType否StringMIME 类型；不传时按 扩展名 → magic bytes 顺序推断
contentLength否Number文件字节数；不传时若来源是 localPath 或 Buffer 会自动推断
cacheControl否Number / String数字会自动转 max-age=<value>；字符串原样作为 Cache-Control 头
metadata否Object自定义 metadata，将被 Base64(JSON) 编码到 X-Metadata 头
xRobotsTag否StringX-Robots-Tag 头
upsert否BooleanPOST 时是否允许覆盖（x-upsert: true），默认 false
usePut否Boolean使用 PUT 方法，等价于强制覆盖；默认 false
accessToken是StringBearer Token
envId否String覆盖当前 envId

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

3. 返回结果​

IUploadObjectHttpResult

字段类型说明
IdString对象 ID
KeyString对象 Key（含路径）

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

字段必填类型说明
bucketId是StringBucket ID
objectName是String对象名
accessToken是StringBearer Token
envId否String覆盖当前 envId

3. 返回结果​

字段类型说明
messageString网关返回提示，例如 Successfully deleted

deleteObjects​

1. 接口描述​

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

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

2. 输入参数​

字段必填类型说明
bucketId是StringBucket ID
prefixes是String[]要删除的对象名列表，1~20 个；字段名虽叫 prefixes，但实际为完整 object name 的精确匹配，并非前缀匹配
accessToken是StringBearer Token
envId否String覆盖当前 envId

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

字段必填类型说明
bucketId是String源 Bucket ID
sourceKey是String源对象名
destinationKey是String目标对象名
destinationBucket否String目标 Bucket ID，默认同源
metadata否Object系统 metadata，仅 copyMetadata=false 时生效，与源 metadata 合并；COS 仅识别 cacheControl / mimetype / contentType
userMetadata否Object用户自定义 metadata，仅 copyMetadata=false 时生效，整体替换 目标 user_metadata（通过 x-metadata Base64(JSON) 头传递）
copyMetadata否Boolean是否复制源对象 metadata，默认 true；true 时忽略请求里的 metadata / userMetadata
upsert否Boolean允许覆盖目标位置已有对象
accessToken是StringBearer Token
envId否String覆盖当前 envId

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

字段必填类型说明
bucketId是String源 Bucket ID
sourceKey是String源对象名
destinationKey是String目标对象名
destinationBucket否String目标 Bucket ID，默认同源
accessToken是StringBearer Token
envId否String覆盖当前 envId

3. 返回结果​

字段类型说明
messageString服务端返回的提示，例如 Successfully moved
IdString目标对象 ID
KeyString目标对象 Key

listObjects​

1. 接口描述​

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

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

2. 输入参数​

字段必填类型说明
bucketId是StringBucket ID
prefix否String路径前缀
limit否Number分页大小，1~1000
cursor否String翻页游标（上一次响应的 nextCursor）
withDelimiter否Boolean是否使用 / 分隔文件夹
sortBy否Object{ column?: 'name' | 'created_at' | 'updated_at', order?: 'asc' | 'desc' }
accessToken是StringBearer Token
envId否String覆盖当前 envId

3. 返回结果​

IListObjectsHttpResult

字段类型说明
foldersIListObjectsFolderItem[]文件夹条目
objectsIListObjectsObjectItem[]对象条目（含 name / id / metadata / created_at / updated_at 等）
hasNextBoolean是否还有下一页
nextCursorString下一页游标
nextCursorKeyString下一页游标 key

signObject​

1. 接口描述​

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

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

2. 输入参数​

字段必填类型说明
bucketId是StringBucket ID
objectName是String对象名
expiresIn是Number过期时间（秒），>= 1
accessToken是StringBearer Token
envId否String覆盖当前 envId

3. 返回结果​

字段类型说明
signedURLString签名下载 URL

signObjects​

1. 接口描述​

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

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

2. 输入参数​

字段必填类型说明
bucketId是StringBucket ID
paths是String[]对象名列表，1~500 个
expiresIn是Number过期时间（秒），>= 1
accessToken是StringBearer Token
envId否String覆盖当前 envId

3. 返回结果​

ISignedObjectItem[]

字段类型说明
pathString对象名
signedURLString / null签名 URL，失败时为 null
errorString / null单条错误信息，成功时为 null

signUploadObject​

1. 接口描述​

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

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

2. 输入参数​

字段必填类型说明
bucketId是StringBucket ID
objectName是String对象名
upsert否Booleantrue 时允许覆盖（x-upsert: true），默认 false
accessToken是StringBearer Token
envId否String覆盖当前 envId

3. 返回结果​

字段类型说明
urlString签名上传 URL
tokenString签名 token，配合 uploadObjectBySign 使用

uploadObjectBySign​

1. 接口描述​

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

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

2. 输入参数​

字段必填类型说明
bucketId是StringBucket ID
objectName是String对象名
token是String由 signUploadObject 获取的签名 token
localPath否String本地文件路径（与 body 二选一）
body否Buffer / NodeJS.ReadableStream文件内容
contentType否String不传则按 扩展名 → magic bytes 推断
contentLength否Number不传则自动推断
envId否String覆盖当前 envId

3. 返回结果​

字段类型说明
KeyString上传成功后的对象 Key

downloadAuthenticatedObject​

1. 接口描述​

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

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

2. 输入参数​

字段必填类型说明
bucketId是StringBucket ID
objectName是String对象名
accessToken是StringBearer Token
method否'GET' / 'HEAD'HTTP 方法，默认 GET
download否String触发浏览器下载，值作为下载文件名
ifNoneMatch否StringIf-None-Match 头
ifModifiedSince否StringIf-Modified-Since 头
range否StringRange 头（断点续传）
envId否String覆盖当前 envId

3. 返回结果​

IDownloadObjectHttpResult

字段类型说明
statusNumberHTTP 状态码（200 / 206 / 304 等）
headersObject响应头（小写 key）
bodyNodeJS.ReadableStream / nullGET 时为可读流；HEAD 时为 null

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

字段必填类型说明
bucketId是StringBucket ID（必须为 public bucket）
objectName是String对象名
method否'GET' / 'HEAD'默认 GET
download否String触发浏览器下载
envId否String覆盖当前 envId

3. 返回结果​

同 downloadAuthenticatedObject。

downloadObjectBySign​

1. 接口描述​

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

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

2. 输入参数​

字段必填类型说明
bucketId是StringBucket ID
objectName是String对象名
token是String签名 token（由 signObject / signObjects 返回的 URL 中提取，或上层业务侧持有）
method否'GET' / 'HEAD'默认 GET
download否String触发浏览器下载
envId否String覆盖当前 envId

3. 返回结果​

同 downloadAuthenticatedObject。

getObjectInfoAuthenticated​

1. 接口描述​

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

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

2. 输入参数​

字段必填类型说明
bucketId是StringBucket ID
objectName是String对象名
method否'GET' / 'HEAD'GET 返回 JSON；HEAD 仅返回响应头
accessToken是StringBearer Token
envId否String覆盖当前 envId

3. 返回结果​

IGetObjectInfoHttpResult

字段类型说明
statusNumberHTTP 状态码
headersObject响应头（小写 key）
bodyIObjectInfoHttpPayload / nullGET 时为对象元信息；HEAD 时为 null

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

字段必填类型说明
bucketId是StringBucket ID（必须为 public bucket）
objectName是String对象名
envId否String覆盖当前 envId

3. 返回结果​

同 getObjectInfoAuthenticated，且 body 一定为 IObjectInfoHttpPayload。