Static Website Hosting

TCB provides developers with static web hosting capabilities, supporting the distribution of static resources such as HTML, CSS, JavaScript, and fonts. Built on Tencent Cloud COS and a global CDN network, it delivers high-performance and high-availability access for your website.

Applicable Scenarios: File-level Operations

The tcb hosting is an operational tool at the file dimension, suitable for the following scenarios:

• Manually upload / synchronize static files (HTML, CSS, JS, images, fonts, etc.)
• Pure static content with no build process (e.g., documentation site artifacts, design mockup exported pages)
• Requires fine-grained control over cloud file paths

If your project has a build step (frontend frameworks like React / Vue / Next.js / Vite / Angular / Nuxt), we recommend using Application Deployment (tcb app deploy), which automatically completes the entire process: install dependencies → build → upload artifacts → bind routes. You can also declaratively deploy multiple sites via tcb deploy by configuring the hosting field in cloudbaserc.json; see Declarative Deployment.

Prerequisites

Before using the CLI to operate the static website service, ensure that:

1. Have a Tencent Cloud account and complete real-name authentication
2. Go to TCB to create a TCB environment

Declarative Deployment (hosting field)

Besides the tcb hosting file-level command, you can also configure the hosting field in cloudbaserc.json and use tcb deploy to declaratively deploy one or more static hosting sites. Declarative deployment supports local build (aligned with Netlify): when buildCommand is non-empty, it automatically runs install + build then uploads artifacts; for pure static, it uploads directly.

Property	Value
Type	Array<Object>
Description	Static hosting app configuration array, each element describing a site's build and upload rules

Sub-fields:

Field	Type	Required	Default	Description
name	String	Yes	—	App name, should be unique within the same config file
root	String	No	.	Project root directory (relative to the directory where cloudbaserc is located), for monorepo
framework	String	No	static	Frontend framework: react/vue/vite/vite-react/vite-vue/next/nuxt/angular/static/custom. Auto-detects from root/package.json when not configured; static/custom means pure static (no build)
installCommand	String	No	npm install	Install command; empty string skips installation
buildCommand	String	No	—	Build command: non-empty triggers local build then artifact upload; empty/unconfigured and undetectable framework skips build, uploads outputDir directly
outputDir	String	No	dist	Build output directory (relative to root). Defaults to dist with build; defaults to root for pure static (no build)
deployPath	String	No	/	Static resource deploy path; multiple hosting should use different paths
envVariables	Object	No	—	Build-time environment variables (non-sensitive)
ignore	String/Array	No	—	Glob patterns for files/directories to ignore during upload

Example:

{
  "hosting": [
    {
      "name": "web",
      "root": "./packages/web",
      "framework": "vite",
      "buildCommand": "npm run build",
      "outputDir": "dist",
      "deployPath": "/web"
    }
  ]
}

Detailed Notes

• name: Unique identifier of the hosting app, referenced by gateway.routes[].target: hosting:<name>
• root: Path relative to the directory containing cloudbaserc, for monorepo setups
• framework presets:
  • react/vue: Generic React/Vue projects, auto-detect build command
  • vite/vite-react/vite-vue: Vite projects, default npm run build, output dist
  • next/nuxt/angular: Next.js/Nuxt/Angular projects, auto-detect
  • static/custom: Pure static (no build), upload outputDir directly
• installCommand: Empty string "" skips installation (for pre-installed deps or monorepos)
• outputDir: Path relative to root; defaults to dist with build, defaults to root for pure static
• deployPath: URL path prefix after deployment, must start with /, unique across hosting apps; corresponds to gateway.routes[].path
• envVariables: Injected into process.env at build time, same mechanism as app.envVariables (not runtime)
• ignore: Glob patterns, e.g. ["node_modules", "*.log", ".git", "dist"]

Deploy Website

Full Deployment

The tcb hosting deploy command deploys all files in the current directory to the static website.

# Go to Build Directory
cd docs

# Deploy all files in the current directory
tcb hosting deploy -e envId

Deploy Specified Files

You can specify specific files or folders for deployment:

# Basic Syntax
tcb hosting deploy <localPath> [cloudPath] -e envId

Parameter Description:

• localPath: Local file or folder path
• cloudPath: Cloud target path (Optional, default is the root directory)
• envId: Environment ID
• --ignore <patterns>: File patterns to ignore, comma-separated (only effective for directory deployment)
• --enable-git-ignore: Merge project .gitignore rules (disabled by default)
• --verify: Verify that remote files match local artifacts after deployment
• --safe: Safe deployment: create a backup before deployment and automatically roll back if upload or verification fails
• --prune: Remove files on the remote that do not belong to the current version after a successful deployment (use with caution; deletes remote files outside this deployment)
• --entry <files>: Specify entry files, comma-separated, relative to the upload directory; uploaded last after all resources finish uploading (default auto-detects every index.html)

Ignore rule syntax, ! negation support, and merge priority are the same as tcb app deploy, see app deploy ignore rule syntax.

Example:

# Deploy all files in the hosting directory to the root directory
tcb hosting deploy hosting -e envId

# Deploy the local index.html to the cloud root directory
tcb hosting deploy ./index.html -e envId

# Deploy the index.js in the static directory to static/index.js in the cloud
tcb hosting deploy ./static/index.js static/index.js -e envId

# Exclude specific files during deployment (comma-separated), directory deployment only
tcb hosting deploy ./dist -e envId --ignore "*.map,.DS_Store"

# Merge project .gitignore rules
tcb hosting deploy ./dist -e envId --enable-git-ignore

Consistent Deployment

tcb hosting deploy supports consistent deployment when deploying a directory, via the --verify, --safe, and --prune switches, making the release process verifiable, rollback-able, and cleanable. Enabling any of these switches triggers the consistent deployment flow: scan local files to build a manifest → (optionally) back up remote → upload → (optionally) verify → (optionally) clean up redundant remote files.

Switch	Description
--verify	Verify that remote files match local artifacts after deployment (compares file size and MD5)
--safe	Safe deployment: create a backup before deployment and automatically roll back if upload or verification fails
--prune	Remove remote files that do not belong to the current version after a successful deployment

--safe Safe Deployment

Before deployment, remote files are backed up under the .cloudbase-backup/<timestamp>/ prefix; if upload or verification fails, they are automatically restored from the backup. Backups are not cleaned up automatically; you can delete them manually after confirming the deployment is correct.

--prune Remove Redundant Remote Files

After a successful deployment, files under the cloud cloudPath that do not exist in the local build artifacts are deleted. Notes:

• --prune requires a second confirmation; append --yes to skip it
• It is recommended to combine with --safe so that accidental deletions can be recovered from the backup
• Only files under the current cloudPath prefix are cleaned up

Examples:

# Verify the deployment matches local artifacts
tcb hosting deploy ./dist --verify

# Safe deployment: automatic rollback on failure
tcb hosting deploy ./dist --safe

# Safe deployment + clean up redundant remote files
tcb hosting deploy ./dist --safe --prune

# Specify entry files (comma-separated)
tcb hosting deploy ./dist --entry index.html,admin/index.html

Deployment Limitations

• File Size: Maximum supported size for a single file is 50TB

• File Count: Unlimited

• Network Optimization: Upload retries are enabled by default (2 times), so transient socket hang up errors will recover automatically. For weak networks or large files, you can further optimize with the following options:

  Option 1: Adjust upload parameters (recommended)

  Parameter	Description	Default
  --concurrency <number>	Upload concurrency. Reduce for large files or weak networks (e.g. 5)	20
  --retry-count <number>	Number of upload retries on failure	2
  --retry-interval <ms>	Retry interval in milliseconds	1000
  --ignore <patterns>	File patterns to ignore, comma-separated (directory deployment only)	—
  --enable-git-ignore	Merge project .gitignore rules	Disabled

  # Large files / weak network: reduce concurrency and increase retries
  tcb hosting deploy ./dist --concurrency 5 --retry-count 3

  Option 2: Disable SDK persistent connections

  export COS_SDK_KEEPALIVE=false
  tcb hosting deploy -e envId

SPA Application Configuration

Vue History Mode

When using Vue Router's history mode, you need to configure the error page as the application's entry page (usually index.html) in the settings page of the Static Website Console.

Website Management

View Service Information

View the status, access domain, and other details of the static website:

tcb hosting detail -e envId

View File List

List all files in the static website storage space:

tcb hosting list -e envId

Delete File

Delete the specified files or folders in the static website:

# Delete Specified Files or Folders
tcb hosting delete <cloudPath> -e envId

# Delete All Files (when cloudPath is empty)
tcb hosting delete -e envId

Command Parameters:

Parameter	Description	Required
cloudPath	Cloud file or folder path	No (if not specified, delete all files)
-e, --env-id <envId>	Environment ID	Yes
--dir	Target is a folder (recursive deletion)	No
--force	Force deletion and skip confirmation prompts	No
--dry-run	Simulate the operation to preview files to be deleted without actual execution	No

Example:

# Delete index.html in the root directory
tcb hosting delete index.html -e envId

# Delete the static folder and all its contents
tcb hosting delete static --dir -e envId

# Preview files to be deleted (without actual execution)
tcb hosting delete static --dir --dry-run -e envId

# Empty the entire static website
tcb hosting delete -e envId

# Force Delete, Skip Confirmation
tcb hosting delete static --dir --force -e envId

Path Description

Path Format

• localPath: Local file or folder path

  • Format: directory/filename
  • Example: ./index.js, static/css/index.css

• cloudPath: Relative path of the cloud file or folder

  • Format: directory/filename (relative to the root directory)
  • Example: index.js, static/css/index.js

Cross-Platform Precautions

Windows System

• localPath: Use the system path format, usually with the \ separator
• cloudPath: Uniformly use the / separator, being independent of the operating system

Frequently Asked Questions

Handling Upload Failures

If you encounter upload failures due to network connection issues, you can try the following:

Option 1: Adjust upload parameters (recommended)

# Large files / weak network: reduce concurrency and increase retries
tcb hosting deploy ./dist --concurrency 5 --retry-count 3

# Customize retry interval (milliseconds)
tcb hosting deploy ./dist --retry-count 5 --retry-interval 2000

Option 2: Disable SDK persistent connections

export COS_SDK_KEEPALIVE=false
tcb hosting deploy -e envId

Domain Access

After deployment is complete, you can access the website via the following methods:

• View the assigned default domain in the console
• Configure custom domain (ICP filing required)