upload.cos

递归上传本地目录或文件到腾讯云 COS（依赖注入，支持并发与进度）。

前置依赖

参数名	类型	说明
deps.COS	COSConstructor	cos-nodejs-sdk-v5
deps.existsSync / statSync / readdirSync	文件系统	遍历本地目录
deps.readFileSync / readFile?	读文件	上传内容
deps.join / basename / relative / normalize	Path	云端 Key 计算
deps.log / error	Console	日志
deps.getSecret	(type) => TencentCloudSecret | null	SecretId/Key

环境要求

• Node.js
• cos-nodejs-sdk-v5

函数签名

function uploadToCOS(
  options: UploadToCOSOptions,
  deps: UploadToCOSDeps,
): Promise<UploadToCOSResult>

类型见 @zengchaowu/shared/types/tencent-cloud。

参数

参数名	类型	必填	说明
options.localPath	string	是	本地文件或目录
options.bucket	string	是	存储桶名称
options.region	string	是	地域
options.cloudPath	string	否	COS 前缀，默认 /
options.secretType	SecretType	是	密钥类型
options.includeRootFolder	boolean	否	是否包含根目录名
options.concurrency	number	否	并发数，默认 10
options.showProgress	boolean	否	控制台进度

返回值

类型	说明
UploadToCOSResult	{ success, message?, uploadedCount?, failedFiles? }

工作原理

1. 校验 localPath 与密钥。
2. 递归收集文件列表，按 relative 计算对象 Key。
3. 并发 putObject，按对象 Key 写入 Cache-Control（见 cacheControlForCosObjectKey）：HTML / 未哈希文件 no-cache, must-revalidate，带内容哈希的 JS/CSS 等 public, max-age=31536000, immutable。
4. 汇总失败文件列表；全部成功则 success: true。

静态站 deploy:cos 成功后还会目录级刷新该域名 CDN 缓存（scripts/lib/after-cos-deploy.mjs）。CDN 节点缓存跟随源站：HTML 短缓存校验，hashed 资源可被边缘与浏览器长期缓存。

异常

配置错误返回 { success: false, message }；单文件失败记入 failedFiles。