deployToTCB

部署文件到腾讯云 TCB（云开发）静态网站托管。

前置依赖

依赖参数

参数名	类型	说明
deps.existsSync	FileSystem['existsSync']	检查文件是否存在
deps.init	CloudBaseManager['init']	腾讯云 CloudBase 管理器初始化函数
deps.log	Console['log']	日志输出函数
deps.error	Console['error']	错误日志函数
deps.getSecret	(type: SecretType) => TencentCloudSecret | null	获取密钥函数

环境要求

• @cloudbase/manager-node: 腾讯云 CloudBase 管理器 SDK

npm install @cloudbase/manager-node

函数签名

function deployToTCB(
  options: DeployOptions,
  deps: DeployTCBDeps
): Promise<DeployResult>

interface DeployOptions {
  /** 本地文件路径 */
  localPath: string
  /** 云端路径 */
  cloudPath?: string
  /** 环境ID */
  envId: string
  /** 密钥类型 */
  secretType: SecretType
  /** 是否显示进度 */
  showProgress?: boolean
}

interface DeployResult {
  success: boolean
  message?: string
  error?: string
}

参数

参数名	类型	必填	说明
options.localPath	string	是	本地文件/文件夹路径
options.cloudPath	string	否	云端路径，默认为 /
options.envId	string	是	云开发环境 ID
options.secretType	SecretType	是	密钥类型（personal/individual/enterprise）
options.showProgress	boolean	否	是否显示上传进度，默认 true

返回值

类型	说明
Promise<DeployResult>	部署结果对象

DeployResult 字段：

字段	类型	说明
success	boolean	是否成功
message	string?	成功消息
error	string?	错误消息

工作原理

1. 验证本地路径是否存在
2. 通过 getSecret 获取腾讯云密钥
3. 使用密钥和环境 ID 初始化 CloudBase 管理器
4. 获取静态网站托管服务实例
5. 调用 uploadFiles 方法上传文件
6. 返回部署结果

示例

基本用法

import { deployToTCB } from 'zcw-shared/functions/tencent-cloud/deploy.tcb'
import type { SecretType, TencentCloudSecret } from 'zcw-shared/types/tencent-cloud'
import CloudBase from '@cloudbase/manager-node'
import fs from 'fs'

// 自定义密钥获取函数
// 注意：实际使用时应该从环境变量或安全的密钥管理服务获取
function getSecret(type: SecretType): TencentCloudSecret | null {
  // 根据类型返回对应的密钥
  // 这里应该从环境变量或密钥管理服务获取，而不是硬编码
  if (type === 'personal') {
    return {
      secretId: process.env.TENCENT_SECRET_ID || '',
      secretKey: process.env.TENCENT_SECRET_KEY || ''
    }
  }
  return null
}

const result = await deployToTCB(
  {
    localPath: './dist',
    cloudPath: '/',
    envId: 'your-env-id',
    secretType: 'personal',
    showProgress: true
  },
  {
    existsSync: fs.existsSync,
    init: CloudBase.init,
    log: console.log,
    error: console.error,
    getSecret
  }
)

if (result.success) {
  console.log('部署成功')
} else {
  console.error(`部署失败: ${result.error}`)
}

部署到指定路径

async function deployToSubPath() {
  const result = await deployToTCB(
    {
      localPath: './docs',
      cloudPath: '/documentation',  // 部署到 /documentation 路径下
      envId: 'my-env-id',
      secretType: 'enterprise',
      showProgress: true
    },
    {
      existsSync: fs.existsSync,
      init: CloudBase.init,
      log: console.log,
      error: console.error,
      getSecret: (type) => {
        // 自定义密钥获取逻辑
        return {
          secretId: process.env.TENCENT_SECRET_ID || '',
          secretKey: process.env.TENCENT_SECRET_KEY || ''
        }
      }
    }
  )

  return result
}

常见错误

本地路径不存在

{ success: false, error: '本地路径不存在: ./dist' }

无效的密钥类型

{ success: false, error: '无效的密钥类型: invalid' }

部署失败

{ success: false, error: '部署失败: Network error' }

注意事项

• 需要先在腾讯云控制台开通云开发服务
• 需要在云开发环境中开启静态网站托管
• 确保密钥有部署权限
• cloudPath 参数会影响文件在云端的路径
• 上传会覆盖云端已存在的同名文件
• 支持上传单个文件或整个文件夹

与 uploadToCOS 的区别

特性	deployToTCB	uploadToCOS
目标服务	云开发静态托管	对象存储 COS
SDK	@cloudbase/manager-node	cos-nodejs-sdk-v5
配置参数	envId	bucket + region
路径控制	cloudPath	cloudPath + includeRootFolder
适用场景	小程序、Web 应用托管	通用对象存储