云存储

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

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

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

3. 返回结果

IUploadObjectHttpResult

字段	类型	说明
Id	String	对象 ID
Key	String	对象 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	是	String	Bucket ID
objectName	是	String	对象名
accessToken	是	String	Bearer Token
envId	否	String	覆盖当前 envId

3. 返回结果

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

deleteObjects

1. 接口描述

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

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

2. 输入参数

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

3. 返回结果

字段	类型	说明
message	String	服务端返回的提示，例如 `Successfully moved`
Id	String	目标对象 ID
Key	String	目标对象 Key

listObjects

1. 接口描述

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

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

2. 输入参数

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

3. 返回结果

IListObjectsHttpResult

字段	类型	说明
folders	IListObjectsFolderItem[]	文件夹条目
objects	IListObjectsObjectItem[]	对象条目（含 `name` / `id` / `metadata` / `created_at` / `updated_at` 等）
hasNext	Boolean	是否还有下一页
nextCursor	String	下一页游标
nextCursorKey	String	下一页游标 key

signObject

1. 接口描述

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

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

2. 输入参数

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

3. 返回结果

字段	类型	说明
signedURL	String	签名下载 URL

signObjects

1. 接口描述

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

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

2. 输入参数

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

3. 返回结果

ISignedObjectItem[]

字段	类型	说明
path	String	对象名
signedURL	String / null	签名 URL，失败时为 null
error	String / null	单条错误信息，成功时为 null

signUploadObject

1. 接口描述

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

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

2. 输入参数

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

3. 返回结果

字段	类型	说明
url	String	签名上传 URL
token	String	签名 token，配合 `uploadObjectBySign` 使用

uploadObjectBySign

1. 接口描述

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

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

2. 输入参数

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

3. 返回结果

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

downloadAuthenticatedObject

1. 接口描述

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

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

2. 输入参数

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

3. 返回结果

IDownloadObjectHttpResult

字段	类型	说明
status	Number	HTTP 状态码（200 / 206 / 304 等）
headers	Object	响应头（小写 key）
body	NodeJS.ReadableStream / null	GET 时为可读流；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	是	String	Bucket 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	是	String	Bucket 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	是	String	Bucket ID
objectName	是	String	对象名
method	否	`'GET'` / `'HEAD'`	GET 返回 JSON；HEAD 仅返回响应头
accessToken	是	String	Bearer Token
envId	否	String	覆盖当前 envId

3. 返回结果

IGetObjectInfoHttpResult

字段	类型	说明
status	Number	HTTP 状态码
headers	Object	响应头（小写 key）
body	IObjectInfoHttpPayload / null	GET 时为对象元信息；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	是	String	Bucket ID（必须为 public bucket）
objectName	是	String	对象名
envId	否	String	覆盖当前 envId

3. 返回结果

同 getObjectInfoAuthenticated，且 body 一定为 IObjectInfoHttpPayload。

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. 接口描述​

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. 接口描述