# 静态网站托管

云开发为开发者提供静态网站托管的能力,静态资源(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
ingore String 或 Array<String> 忽略文件模式

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

当需要上传多个文件时,请指定 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.jsstatic/css/index.css 等。
  • cloudPath 为文件或文件夹的相对根目录的路径,为 目录/文件名 的形式,如 index.jsstatic/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> 静态网站配置

# 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

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

# ITcbDomainConfig

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

# ITcbReferer

字段 必填 类型 说明
Switch String referer 黑白名单配置开关 on:开启 off:关闭
RefererRules Array.<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> 缓存策略
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()