支持地域：上海

静态网站托管

云开发为开发者提供静态网站托管的能力，静态资源（HTML、CSS、JavaScript、字体等）的分发由对象存储 COS 和拥有多个边缘网点的 CDN 提供支持。您可在腾讯云控制台进行静态网站的部署，提供给您的用户访问。目前云开发静态网站托管能力仅在腾讯云云开发控制台支持，小程序 IDE 侧控制台暂不支持。

uploadFiles

新增于 3.1.0 版本

1. 接口描述

接口功能：上传单个文件，多个文件，文件夹到静态网站托管中

接口声明：async uploadFiles(options: IHostingOptions)

2. 输入参数

字段	必填	类型	说明
localPath	否	String	单个文件或文件夹的本地路径
cloudPath	否	String	单个文件或文件夹的云端路径
files	否	`Array<{localPath:string; cloudPath:string}>`	由 localPath 和 cloudPath 文件信息组成的数组，用于上传多个文件
onProgress	否	Function	上传进度回调事件，会在上传过程中多次触发
onFileFinish	否	(err, data) => void	每个文件上传完成后的回调，如果上传失败，则回调 err
ignore	否	String 或 `Array<String>`	忽略文件模式（glob 模式，如 `['/node_modules/']`）

上传文件夹时，请指定 localPath 和 cloudPath参数，文件夹下的所有文件会上传到指定目录下，不包含文件夹本身。

当需要上传多个文件时，请指定 files 参数。

当 cloudPath为空时，文件会被上传到根目录下。

3. 返回结果

4. 示例代码

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

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

async function test() {
  // 上传文件夹
  await hosting.uploadFiles({
    localPath: "./dir",
    cloudPath: "",
    ignore: ["**/ignore.*"],
  });
  let fileCount = 0;
  // 上传多个文件
  await hosting.uploadFiles({
    files: [
      {
        localPath: "test/storage/test_data/data.txt",
        cloudPath: "hosting/test_data/data.txt",
      },
    ],
    ignore: ["**/ignore.*"],
    onFileFinish: () => {
      fileCount++;
    },
  });
  console.log(fileCount); // 1
}

test();

listFiles

新增于 3.1.0 版本

1. 接口描述

接口功能：获取全部文件列表

接口声明：async listFiles(): Promise<IListFileInfo[]>

2. 输入参数

无

3. 返回结果

字段	类型	说明
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 { hosting } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
});

async function test() {
  const res1 = await hosting.listFiles();
  for (let item in res1) {
    console.log(item);
  }
}
test();

deleteFiles

新增于 3.1.0 版本

1. 接口描述

接口功能：删除静态网站托管的文件或文件夹

接口声明：async deleteFiles(options: IHostingCloudOptions)

2. 参数说明

字段	必填	类型	说明
cloudPath	是	String	文件或文件夹的云端路径
isDir	否	Boolean	cloudPath 是否为文件夹

3. 返回结果

无

4. 示例代码

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

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

async function test() {
  await hosting.deleteFiles({
    cloudPath: "files/data.txt",
    isDir: false,
  });
}

test();

关于路径

localPath 为本地文件或文件夹的路径，为 目录/文件名 的形式，如 ./index.js、static/css/index.css 等。
cloudPath 为文件或文件夹的相对根目录的路径，为 目录/文件名 的形式，如 index.js、static/css/index.js 等。

注意事项

Windows 系统中 localPath 为本地路径形式，是系统可以识别的路径，通常使用 \ 分隔符。cloudPath 是云端文件路径，均需要使用 / 分隔符。

findFiles

新增于 3.2.0 版本

1. 接口描述

接口功能：搜索静态网站托管的文件(支持按前缀搜索文件名称)

接口声明：async findFiles(options: IFindOptions)

2. 参数说明

字段	必填	类型	说明
prefix	是	String	匹配前缀，限定响应中只包含指定前缀的文件(对象)
marker	否	Boolean	起始对象键标记，从该标记之后（不含）按照 UTF-8 字典序返回对象键条目
maxKeys	否	Boolean	单次返回最大的条目数量，默认值为 1000，最大为 1000

3. 返回结果

字段	必填	类型	说明
Name	是	String	存储桶的名称，格式为<BucketName-APPID>
Prefix	是	String	对象键匹配前缀，对应请求中的 prefix 参数
Marker	是	String	起始对象键标记，从该标记之后（不含）按照 UTF-8 字典序返回对象键条目，对应请求中的 marker 参数
MaxKeys	是	Number	单次响应返回结果的最大条目数量，对应请求中的 max-keys 参数
Contents	是	IContentItem	对象条目

IContentItem

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

IOwnerInfo

字段	必填	类型	说明
ID	是	String	对象持有者的 APPID
DisplayName	是	String	对象持有者的名称

4. 示例代码

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

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

async function test() {
  const { Contents } = await hosting.findFiles({
    prefix: "hosting/",
    marker: "/",
  });

  console.log(Contents);
}

test();

setWebsiteDocument

新增于 3.2.0 版本

1. 接口描述

接口功能：配置静态网站的错误文档，索引文档，重定向规则

接口声明：async setWebsiteDocument(options: IBucketWebsiteOptiosn)

2. 参数说明

字段	必填	类型	说明
indexDocument	是	String	文档地址
errorDocument	否	String	文档地址
routingRules	否	IRoutingRules	文档地址

IRoutingRules

字段	必填	类型	说明
keyPrefixEquals	否	String	指定前缀重定向的路径，替换指定的 folder/
httpErrorCodeReturnedEquals	否	String	指定重定向错误码，只支持配置 4XX 返回码，优先级高于 ErrorDocument
replaceKeyWith	否	String	替换整个 Key 为指定的内容
replaceKeyPrefixWith	否	String	替换匹配到的前缀为指定的内容，设置 KeyPrefixEquals 时才可设置

注：设置前缀匹配 keyPrefixEquals 时，替换内容可指定 replaceKeyWith(替换整个路径) 或 replaceKeyPrefixWith(替换前缀)，设置指定重定向错误码 httpErrorCodeReturnedEquals 时，只能指定 replaceKeyWith(替换整个路径)

3. 返回结果

字段	必填	类型	说明
statusCode	是	Number	请求返回的 HTTP 状态码，如 200、403、404 等
headers	否	Object	请求返回的头部信息

4. 示例代码

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

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

async function test() {
  const res = await hosting.setWebsiteDocument({
    errorDocument: "error.html",
    indexDocument: "success.html",
    routingRules: [
      {
        keyPrefixEquals: "test.html",
        replaceKeyWith: "index.html",
      },
      {
        keyPrefixEquals: "test1.html",
        replaceKeyPrefixWith: "index1.html",
      },
      {
        httpErrorCodeReturnedEquals: "400",
        replaceKeyWith: "index.html",
      },
    ],
  });

  if (res.statusCode === 200) {
    // todo
  }
}

test();

CreateHostingDomain

新增于 3.2.0 版本

1. 接口描述

接口功能：绑定自定义域名

接口声明：async CreateHostingDomain(options: IBindDomainOptions)

2. 参数说明

字段	必填	类型	说明
domain	是	String	自定义域名
certId	是	String	证书 ID

3. 返回结果

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

4. 示例代码

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

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

async function test() {
  const res = await hosting.CreateHostingDomain({
    domain: "xxx.xxx.xxx",
    certId: "xxxxx",
  });
  console.log(res);
}

test();

deleteHostingDomain

新增于 3.3.0 版本

1. 接口描述

接口功能：解绑自定义域名

接口声明：async deleteHostingDomain(options: IDeleteDomainOptions)

2. 参数说明

字段	必填	类型	说明
domain	是	String	自定义域名

3. 返回结果

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

4. 示例代码

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

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

async function test() {
  const res = await hosting.deleteHostingDomain({
    domain: "xxx.xxx.xxx",
  });
  console.log(res);
}

test();

getWebsiteConfig

新增于 3.3.0 版本

1. 接口描述

接口功能：获取静态网站配置

接口声明：async getWebsiteConfig()

2. 参数说明

无

3. 返回结果

字段	必填	类型	说明
statusCode	是	Number	请求返回的 HTTP 状态码，如 200、403、404 等
headers	是	Object	请求返回的头部信息
WebsiteConfiguration	是	IWebsiteConfig	静态网站配置

IWebsiteConfig

字段	必填	类型	说明
IndexDocument	是	IIndexDocument	索引文档
ErrorDocument	是	IErrorDocument	错误文档
RoutingRules	是	`Array<[IRoutingRule](#IRoutingRule)>`	静态网站配置

IIndexDocument

字段	必填	类型	说明
Suffix	是	String	指定索引文档

IErrorDocument

字段	必填	类型	说明
Key	是	String	指定通用错误返回

IRoutingRule

字段	必填	类型	说明
Condition	是	ICondition	指定重定向发生的条件，前缀匹配重定向和错误码重定向只能指定一个
Redirect	是	IRedirect	指定满足重定向 conditon 时重定向的具体替换规则

ICondition

字段	必填	类型	说明
HttpErrorCodeReturnedEquals	是	String	指定重定向错误码，只支持配置 4XX 返回码，优先级高于 ErrorDocument
KeyPrefixEquals	是	String	指定前缀重定向的路径，替换指定的 folder/

IRedirect

字段	必填	类型	说明
ReplaceKeyWith	是	String	替换整个 Key 为指定的内容
ReplaceKeyPrefixWith	是	String	替换匹配到的前缀为指定的内容，Conditon 为 KeyPrefixEquals 才可设置

4. 示例代码

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

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

async function test() {
  const getConfig = await hosting.getWebsiteConfig();
  console.log("getConfig :", getConfig);
}

test();

tcbCheckResource

新增于 3.3.0 版本

1. 接口描述

接口功能：获取域名配置

接口声明：async tcbCheckResource(options: ICheckSourceOptions)

2. 参数说明

字段	必填	类型	说明
domains	是	`Array<String>`	域名列表

3. 返回结果

字段	必填	类型	说明
RecordCount	是	Number	记录域名数
RequestId	是	String	唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。
Domains	是	`Array<[ITcbDomainInfo](#ITcbDomainInfo)>`	域名清单

ITcbDomainInfo

字段	必填	类型	说明
Domain	是	String	域名
DomainId	是	Number	域名 Id
Status	是	String	process , online , offline 域名状态
DomainConfig	是	ITcbDomainConfig	域名配置
CName	是	String	域名 CName

ITcbDomainConfig

字段	必填	类型	说明
Refer	否	ITcbReferer	Referer 防盗链配置
Cache	否	`Array<[ITcbCache](#ITcbCache)>`	缓存策略列表
IpFilter	否	IIpFilter	IP 黑白名单配置
IpFreqLimit	否	IIpFreqLimit	IP 限频配置

ITcbReferer

字段	必填	类型	说明
Switch	是	String	referer 黑白名单配置开关 on：开启 off：关闭
RefererRules	否	`Array<[ITcbRefererRule](#ITcbRefererRule)>`	referer 黑白名单配置规则 switch 为 on 时必填

ITcbRefererRule

字段	必填	类型	说明
RefererType	是	String	referer 配置类型, whitelist：白名单, blacklist：黑名单
Referers	是	`Array<String>`	referer 内容列表,列表最大长度 400 个, 不需要 http://开头，填写形如:www.test.com
AllowEmpty	是	Boolean	是否允许空 referer, true：允许空 refere, false：不允许空 referer

ITcbCache

| 字段 | 必填 | 类型 | 说明 | | --------- | ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | | RuleType | 是 | String | 规则类型 all 全部文件,suffix 按后缀名匹配, path 文件夹类型按目录匹配, file 全路径匹配四选一必填。 | | RuleValue | 是 | String | 规则内容依据规则类型而不同以;分割必填，suffix 类型每个后缀不超过 10 字节，总长度不超过 512 字节，file 不能以/或结尾，path 不能包含; | \/<>" | | CacheTtl | 是 | Number | Number | 缓存时间单位秒必填 |

IIpFilter

字段	必填	类型	说明
Switch	是	String	IP 黑白名单配置开关,on：开启,off：关闭
FilterType	否	String	IP 黑白名单类型,whitelist：白名单,blacklist：黑名单
Filters	否	`Array<String>`	IP 黑白名单列表,支持 X.X.X.X 形式 IP，或 /8、 /16、/24 形式网段,最多可填充 50 个白名单或 50 个黑名单

IIpFreqLimit

字段	必填	类型	说明
Switch	是	String	IP 限频配置开关, on：开启, off：关闭
Qps	否	Number	设置每秒请求数限制,超出限制的请求会直接返回 514

4. 示例代码

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

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

async function test() {
  const res = await hosting.tcbCheckResource({
    domains: ["domain"],
  });
  console.log("res:", res);
}

test();

tcbModifyAttribute

新增于 3.3.0 版本

1. 接口描述

接口功能：域名配置

接口声明：async tcbModifyAttribute(options: IModifyOptions)

2. 参数说明

字段	必填	类型	说明
Domain	是	String	域名
DomainId	是	Number	域名 Id
DomainConfig	是	ITcbDomainConfig	域名配置

3. 返回结果

字段	必填	类型	说明
DomainId	是	Number	域名 Id
Origin	是	ITcbOrigin	cos 源域名
CosPrivateAccess	是	String	yes,no 是否开始 cos 私有读
Authentication	是	ITcbAuthentication	防盗链 key
Cache	是	`Array<[ITcbCache](#ITcbCache)>`	缓存策略
StaticWeb	是	ITcbStatic	静态网站
RootAccess	是	String	no off，是否访问根目录
RequestId	是	String	唯一请求 ID，每次请求都会返回

ITcbOrigin

字段	必填	类型	说明
Master	是	String	主站
Slave	否	String	副站

ITcbAuthentication

字段	必填	类型	说明
Switch	是	String	on/off 开启或关闭’
SecretKey	是	String	开启时必填，用户计算签名的秘钥，仅支持字母和数字组合，6 到 32 位
SignParam	否	String	url 串中签名的字段名，字母数字组合，不能以数字开头，低于 32 位，默认为 sign
TimeParam	否	String	url 串中时间的字段名，字母数字组合，不能以数字开头，，低于 32 位，默认为 t
ExpireTime	否	Number	开启时必填过期时间，小于 31536000 秒，单位为秒

ITcbStatic

| 字段 | 必填 | 类型 | 说明 | | ------ | ---- | ------ | --------------------------------------------------- | ------- | | Switch | 是 | String | 开启，关闭静态网站功能 | | Path | 否 | String | 静态网站跳转的路径，以/开头，不支持路径包含空白和; | /<>\*" |

4. 示例代码

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

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

async function test() {
  const res = await hosting.tcbCheckResource({
    domains: ["domain"],
  });
  const domainId = res.Domains[0].DomainId;

  const setRes = await hosting.tcbModifyAttribute({
    domain: "domain",
    domainId,
    domainConfig: {
      Refer: {
        Switch: "on",
        RefererRules: [
          {
            AllowEmpty: false,
            RefererType: "blacklist",
            Referers: ["www.test11.com"],
          },
        ],
      },
      IpFilter: {
        Switch: "on",
        FilterType: "blacklist",
        Filters: ["xxx.xxx.xxx.xxx"],
      },
      IpFreqLimit: {
        Switch: "on",
        Qps: 100,
      },
      Cache: [
        {
          RuleType: "suffix",
          RuleValue: ".jpg",
          CacheTtl: 60,
        },
      ],
    },
  });

  console.log("setRes:", setRes);
}

test();

downloadFile

1. 接口描述

接口功能：从静态托管下载单个文件到本地，或返回可读流

接口声明：app.hosting.downloadFile(options): Promise<NodeJS.ReadableStream | string>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
cloudPath	是	String	云端文件路径（相对于托管根目录），例如 `images/logo.png`
localPath	否	String	本地保存的完整文件路径，例如 `./dist/logo.png`；不传时返回可读流

3. 返回结果

情况	返回类型	说明
传入 `localPath`	`Promise<string>`	文件写入完成后返回本地绝对路径
不传 `localPath`	`Promise<NodeJS.ReadableStream>`	返回可读流，可自行消费

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 localPath = await app.hosting.downloadFile({
    cloudPath: "images/logo.png",
    localPath: "./dist/logo.png",
  });
  console.log("文件已保存至:", localPath);

  // 获取可读流（自行处理）
  const stream = await app.hosting.downloadFile({
    cloudPath: "data/report.csv",
  });
  stream.pipe(process.stdout);
}

test();

downloadDirectory

1. 接口描述

接口功能：批量下载云端目录下的所有文件到本地

接口声明：app.hosting.downloadDirectory(options): Promise<void>

版本提示

自 v5.0.0 起支持此接口

内部并发度为 20，底层复用 downloadFile。空目录和路径条目自动跳过。

2. 输入参数

字段	必填	类型	说明
cloudPath	是	String	云端目录路径，例如 `assets/`
localPath	否	String	本地目标目录路径；目录不存在时自动创建；不传则以当前工作目录为根

3. 返回结果

Promise<void> — 全部文件下载完成后 resolve。

4. 示例代码

async function test() {
  await app.hosting.downloadDirectory({
    cloudPath: "assets/",
    localPath: "./local-assets",
  });
  console.log("目录下载完成");
}

test();

uploadFiles​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

listFiles​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 代码示例​

deleteFiles​

1. 接口描述​

2. 参数说明​

3. 返回结果​

4. 示例代码​

关于路径​

findFiles​

1. 接口描述​

2. 参数说明​

3. 返回结果​

IContentItem​

IOwnerInfo​

4. 示例代码​

setWebsiteDocument​

1. 接口描述​

2. 参数说明​

IRoutingRules​

3. 返回结果​

4. 示例代码​

CreateHostingDomain​

1. 接口描述​

2. 参数说明​

3. 返回结果​

4. 示例代码​

deleteHostingDomain​

1. 接口描述​

2. 参数说明​

3. 返回结果​

4. 示例代码​

getWebsiteConfig​

1. 接口描述​

2. 参数说明​

3. 返回结果​

IWebsiteConfig​

IIndexDocument​

IErrorDocument​

IRoutingRule​

ICondition​

IRedirect​

4. 示例代码​

tcbCheckResource​

1. 接口描述​

2. 参数说明​

3. 返回结果​

ITcbDomainInfo​

ITcbDomainConfig​

ITcbReferer​

ITcbRefererRule​

ITcbCache​

IIpFilter​

IIpFreqLimit​

4. 示例代码​

tcbModifyAttribute​

1. 接口描述​

2. 参数说明​

3. 返回结果​

ITcbOrigin​

ITcbAuthentication​

ITcbStatic​

4. 示例代码​

downloadFile​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

downloadDirectory​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

uploadFiles

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

listFiles

1. 接口描述

2. 输入参数

3. 返回结果

4. 代码示例

deleteFiles

1. 接口描述

2. 参数说明

3. 返回结果

4. 示例代码

关于路径

findFiles

1. 接口描述

2. 参数说明

3. 返回结果

IContentItem

IOwnerInfo

4. 示例代码

setWebsiteDocument

1. 接口描述

2. 参数说明

IRoutingRules

3. 返回结果

4. 示例代码

CreateHostingDomain

1. 接口描述

2. 参数说明

3. 返回结果

4. 示例代码

deleteHostingDomain

1. 接口描述

2. 参数说明

3. 返回结果

4. 示例代码

getWebsiteConfig

1. 接口描述

2. 参数说明

3. 返回结果

IWebsiteConfig

IIndexDocument

IErrorDocument

IRoutingRule

ICondition

IRedirect

4. 示例代码

tcbCheckResource

1. 接口描述

2. 参数说明

3. 返回结果

ITcbDomainInfo

ITcbDomainConfig

ITcbReferer

ITcbRefererRule

ITcbCache

IIpFilter

IIpFreqLimit

4. 示例代码

tcbModifyAttribute

1. 接口描述

2. 参数说明

3. 返回结果

ITcbOrigin

ITcbAuthentication

ITcbStatic

4. 示例代码

downloadFile

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

downloadDirectory

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码