跳到主要内容

静态网站托管

云开发为开发者提供静态网页托管能力，支持 HTML、CSS、JavaScript、字体等静态资源的分发。底层基于腾讯云对象存储 COS 和全球 CDN 网络，为您的网站提供高性能、高可用的访问体验。

适用场景：文件级操作

tcb hosting 是文件维度的操作工具，适合以下场景：

  • 手动上传 / 同步静态文件（HTML、CSS、JS、图片、字体等）
  • 纯静态内容，无构建流程（如文档站产物、设计稿导出页面）
  • 需要精细控制云端文件路径

如果你的项目有构建步骤（React / Vue / Next.js / Vite / Angular / Nuxt 等前端框架），推荐使用 应用部署（tcb app deploy），它会自动完成安装依赖 → 构建 → 上传产物 → 绑定路由的完整流程。也可通过 tcb deploy 在 cloudbaserc.json 中配置 hosting 字段声明式部署多站点，见 声明式部署。

前置条件​

在使用 CLI 操作静态网站服务前，请确保：

  1. 拥有腾讯云账号并完成实名认证
  2. 前往云开发平台，创建云开发环境

声明式部署（hosting 字段）​

除了 tcb hosting 文件级命令，也可以在 cloudbaserc.json 中配置 hosting 字段，通过 tcb deploy 一键声明式部署一个或多个静态托管站点。声明式部署支持本地构建（对齐 Netlify）：buildCommand 非空时自动执行 install + build 后上传产物；纯静态时直接上传。

属性值
类型Array<Object>
说明静态托管应用配置数组，每个元素描述一个站点的构建与上传规则

子字段：

字段类型必填默认值说明
nameString是—应用名称，同一配置文件内应唯一
rootString否.项目根目录（相对 cloudbaserc 所在目录），用于 monorepo
frameworkString否static前端框架：react/vue/vite/vite-react/vite-vue/next/nuxt/angular/static/custom。未配置时自动读取 root/package.json 检测；static/custom 表示纯静态（不构建）
installCommandString否npm install安装命令；空字符串表示跳过安装
buildCommandString否—构建命令：非空则本地构建后上传产物；空字符串/未配置且无法检测框架时跳过构建，直接上传 outputDir
outputDirString否dist构建产物目录（相对 root）。有构建时默认 dist；纯静态（无构建）时默认 root
deployPathString否/静态资源部署路径，多个 hosting 应使用不同路径
envVariablesObject否—构建时环境变量（非敏感）
ignoreString/Array否—上传时忽略的文件/目录 glob 模式

示例：

{
  "hosting": [
    {
      "name": "web",
      "root": "./packages/web",
      "framework": "vite",
      "buildCommand": "npm run build",
      "outputDir": "dist",
      "deployPath": "/web"
    }
  ]
}
补充说明
  • name：hosting 应用的唯一标识，被 gateway.routes[].target: hosting:<name> 引用
  • root：相对 cloudbaserc 所在目录的路径，配合 monorepo 多包部署
  • framework 框架预设：
    • react/vue：通用 React/Vue 项目，自动检测构建命令
    • vite/vite-react/vite-vue：Vite 项目，默认 npm run build，产物 dist
    • next/nuxt/angular：Next.js/Nuxt/Angular 项目，自动检测
    • static/custom：纯静态（不构建），直接上传 outputDir
  • installCommand：空字符串 "" 跳过安装步骤（适用于已预装依赖或 monorepo）
  • outputDir：相对 root 的路径；有构建时默认 dist；纯静态默认 root
  • deployPath：上线后访问路径前缀，必须以 / 开头，多个 hosting 不可重复；与 gateway.routes[].path 对应
  • envVariables：构建时注入到 process.env，与 app.envVariables 是同一机制（非运行时环境变量）
  • ignore：glob 模式，如 ["node_modules", "*.log", ".git", "dist"]

部署网站​

全量部署​

使用 tcb hosting deploy 命令可以将当前目录下的所有文件部署到静态网站。

# 进入构建目录
cd docs

# 部署当前目录下的所有文件
tcb hosting deploy -e envId

指定文件部署​

您可以指定特定的文件或文件夹进行部署：

# 基本语法
tcb hosting deploy <localPath> [cloudPath] -e envId

参数说明：

  • localPath：本地文件或文件夹路径
  • cloudPath：云端目标路径（可选，默认为根目录）
  • envId：环境 ID
  • --ignore <patterns>：忽略文件模式，逗号分隔（仅目录部署时生效）
  • --enable-git-ignore：合并项目 .gitignore 规则（默认不合并）
  • --verify：发布后校验远端文件与本地产物一致
  • --safe：安全发布：发布前创建备份，上传或校验失败时自动回滚
  • --prune：发布成功后清理远端不属于当前版本的文件（谨慎使用，将删除本次发布内容之外的远端文件）
  • --entry <files>：指定入口文件，逗号分隔，相对上传目录；资源上传完成后最后上传（默认自动识别各级 index.html）

忽略规则的语法、! 取反支持情况与合并优先级同 tcb app deploy，见 app deploy 忽略规则语法。

示例：

# 将 hosting 目录下的所有文件部署到根目录
tcb hosting deploy hosting -e envId

# 将本地 index.html 部署到云端根目录
tcb hosting deploy ./index.html -e envId

# 将 static 目录下的 index.js 部署到云端 static/index.js
tcb hosting deploy ./static/index.js static/index.js -e envId

# 部署时排除指定文件（逗号分隔），仅目录部署生效
tcb hosting deploy ./dist -e envId --ignore "*.map,.DS_Store"

# 合并项目 .gitignore 规则
tcb hosting deploy ./dist -e envId --enable-git-ignore

一致性发布​

tcb hosting deploy 在部署目录时支持一致性发布能力，通过 --verify、--safe、--prune 三个开关组合使用，保证发布过程可校验、可回滚、可清理。使用任一开关时，目录上传即进入一致性发布流程：扫描本地文件生成清单 →（可选）备份远端 → 上传 →（可选）校验 →（可选）清理远端冗余文件。

参数说明
--verify发布后校验远端文件与本地产物一致（对比文件大小与 MD5）
--safe安全发布：发布前创建备份，上传或校验失败时自动回滚
--prune发布成功后清理远端不属于当前版本的文件

--safe 安全发布

发布前会将远端文件备份到 .cloudbase-backup/<时间戳>/ 前缀下；若上传或校验失败，自动从备份回滚。备份不会自动清理，确认发布无误后可手动删除。

--prune 清理远端冗余文件

发布成功后，删除云端 cloudPath 下、本地构建产物中不存在的文件。注意：

  • --prune 会进行二次确认，追加 --yes 可跳过确认
  • 建议配合 --safe 使用，误删时可通过备份恢复
  • 仅清理当前 cloudPath 前缀下的文件

示例：

# 校验发布结果与本地产物一致
tcb hosting deploy ./dist --verify

# 安全发布：失败自动回滚
tcb hosting deploy ./dist --safe

# 安全发布 + 清理远端冗余文件
tcb hosting deploy ./dist --safe --prune

# 指定入口文件（逗号分隔）
tcb hosting deploy ./dist --entry index.html,admin/index.html

部署限制​

  • 文件大小：单个文件最大支持 50TB

  • 文件数量：无限制

  • 网络优化：上传默认开启 2 次自动重试，瞬时 socket hang up 会自动恢复。弱网或大文件场景可通过以下方式进一步优化：

    方式一：调整上传参数（推荐）

    参数说明默认值
    --concurrency <number>上传并发数，大文件或弱网建议调小（如 5）20
    --retry-count <number>上传失败重试次数2
    --retry-interval <ms>重试时间间隔（毫秒）1000
    # 大文件 / 弱网：降低并发 + 增加重试次数
    tcb hosting deploy ./dist --concurrency 5 --retry-count 3

    方式二：关闭 SDK 长连接

    export COS_SDK_KEEPALIVE=false
    tcb hosting deploy -e envId

SPA 应用配置​

Vue History 模式

使用 Vue Router 的 history 模式时，需要在 静态网站控制台 的设置页面配置错误页面为应用的入口页面（通常是 index.html）。

管理网站​

查看服务信息​

查看静态网站的状态、访问域名等详细信息：

tcb hosting detail -e envId

查看文件列表​

列出静态网站存储空间中的所有文件：

tcb hosting list -e envId

删除文件​

删除静态网站中的指定文件或文件夹：

# 删除指定文件或文件夹
tcb hosting delete <cloudPath> -e envId

# 删除所有文件（cloudPath 为空）
tcb hosting delete -e envId

命令参数:

参数说明必填
cloudPath云端文件或文件夹路径否（不指定则删除所有文件）
-e, --env-id <envId>环境 ID是
--dir删除目标是文件夹（递归删除）否
--force强制删除，跳过确认提示否
--dry-run模拟运行，仅预览将要删除的文件，不实际执行否

示例：

# 删除根目录下的 index.html
tcb hosting delete index.html -e envId

# 删除 static 文件夹及其所有内容
tcb hosting delete static --dir -e envId

# 预览将要删除的文件（不实际执行）
tcb hosting delete static --dir --dry-run -e envId

# 清空整个静态网站
tcb hosting delete -e envId

# 强制删除，跳过确认
tcb hosting delete static --dir --force -e envId

路径说明​

路径格式​

  • localPath：本地文件或文件夹路径

    • 格式：目录/文件名
    • 示例：./index.js、static/css/index.css

  • cloudPath：云端文件或文件夹的相对路径

    • 格式：目录/文件名（相对于根目录）
    • 示例：index.js、static/css/index.js

跨平台注意事项​

Windows 系统
  • localPath：使用系统路径格式，通常使用 \ 分隔符
  • cloudPath：统一使用 / 分隔符，与操作系统无关

常见问题​

上传失败处理​

如果遇到网络连接问题导致上传失败，可以尝试以下方式：

方式一：调整上传参数（推荐）

# 大文件 / 弱网：降低并发并增加重试次数
tcb hosting deploy ./dist --concurrency 5 --retry-count 3

# 调整重试间隔（毫秒）
tcb hosting deploy ./dist --retry-count 5 --retry-interval 2000

方式二：关闭 SDK 长连接

export COS_SDK_KEEPALIVE=false
tcb hosting deploy -e envId

域名访问​

部署完成后，您可以通过以下方式访问网站：

  • 在控制台查看分配的默认域名
  • 配置自定义域名（需要 ICP 备案）