跳到主要内容

静态网站托管

云开发为开发者提供静态网页托管能力，支持 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. 前往云开发平台，创建云开发环境

静态网站服务需要开通后才能使用：平台版账号创建环境时会自动分配静态托管资源，无需手动开通；普通账号需先开通。tcb hosting 的部署、查看、删除、下载命令只查询托管状态、不会代为开通，未开通时会直接报错——可运行 tcb hosting detail 按提示开通，或先在云开发控制台开通。

声明式部署（hosting 字段）​

除了 tcb hosting 文件级命令，也可以在 cloudbaserc.json 中配置 hosting 字段，通过 tcb deploy 一键声明式部署一个或多个静态托管站点。构建与部署分离（自 CLI v3.8.2 起）：

  1. 构建：执行 tcb app build 在本地运行 buildCommand 生成产物（不安装依赖、不部署）
  2. 部署：执行 tcb deploy 上传产物并编排部署其余资源

hosting 配置了 buildCommand 时，tcb deploy 不再自动执行本地构建——产物目录不存在会报错并提示先执行 tcb app build；纯静态（无 buildCommand）直接上传，无需构建。

属性值
类型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否—安装命令，不再被 CLI 本地执行（依赖由用户自行安装，对齐业界做法）
buildCommandString否—构建命令：非空则先执行 tcb app build 本地构建；tcb deploy 不再自动构建，产物缺失会报错。空字符串/未配置且无法检测框架时为纯静态，直接上传 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：保留用于兼容旧配置，不再被本地执行——依赖需先自行安装（如 npm install），tcb app build 不代为安装
  • 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 / list / delete / download）只查询服务状态、不会代为开通，未开通时命令直接报错——请运行 tcb hosting detail 按提示开通，或在云开发控制台开通后重试。

服务刚开通时资源仍在初始化（状态为「初始化中」或「处理中」），此时上传会被服务端拒绝。命令会自动等待服务就绪（每 5 秒轮询，最长约 6 分钟）后继续；如果等待超时，稍后重新执行即可。

指定文件部署​

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

# 基本语法
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 备案）