推荐使用 tencent.qcloud.cos.sdk（非 cosxml），初始化需正确传入 region 和子用户 secretid/secretkey，避免硬编码；大文件上传应使用 transfermanager 并配置重试与分块参数；对象 key 必须 url 编码，cdn 加速需开启回源鉴权并配置完整证书链。
直接用 Tencent.QCloud.Cos.Sdk 是当前 C# 项目接入 COS 最稳定、官方维护最及时的方式。别碰旧版 CosXml 手动封装或自己拼签名，容易在签名过期、Region 处理、STS 临时凭证适配上翻车。
初始化 CosXmlServer 必须传对 Region 和 SecretId/SecretKey
Region 错了会报 CosClientException: InvalidBucketName 或直接超时；SecretId/SecretKey 权限不足则提示 AccessDenied。这两个值不能硬编码进源码，应从环境变量或配置中心读取：
-
COS_REGION值必须是地域简称，如ap-guangzhou，不是“广州”或gz -
SECRET_ID和SECRET_KEY强烈建议用子用户密钥，并只授予cos:GetObject、cos:PutObject等最小必要权限 - 若用 STS 临时凭证，需改用
STSCredentialProvider，且durationSecond不宜设超过 2 小时，否则 COS 后端可能拒绝
上传文件时 TransferManager 比 COSXMLUploadTask 更可靠
COSXMLUploadTask 是低层封装，不自动处理分块上传、断点续传和重试逻辑；实际生产中推荐用 TransferManager：
- 大文件（>5MB）默认走分块上传，
TransferConfig可调partSize（默认 5MB）和maxThread（默认 5） - 网络抖动时会自动重试，但重试次数默认为 0，需显式设置
retryCount -
srcPath必须是本地绝对路径，相对路径如"output_file1.sql"在非 Debug 目录下会找不到
下载/查询元数据前先确认对象键（key）是否含非法字符
COS 对象键本质是 URL 路径，空格、中文、#、? 等字符会导致 HeadObjectRequest 或 GetObjectRequest 返回 403 或 404，而不是你预期的“文件不存在”。解决方法只有两个：
- 上传时就用
Uri.EscapeDataString(key)编码 key，比如把"测试文件.txt"转成"%E6%B5%8B%E8%AF%95%E6%96%87%E4%BB%B6.txt" - 下载或查元数据时，也必须用完全相同的编码后 key 发起请求，不能一边编码一边不编码
- 注意：
bucket名称格式必须为bucketname-APPID，少一个连字符或 APPID 错一位都会报InvalidBucketName
CDN 加速域名必须开启回源鉴权并匹配证书链
前端加载 COS 图片慢，加 CDN 是对的，但常见卡点不在 COS 侧，而在 CDN 配置：
- COS 控制台里添加的自定义 CDN 域名，必须勾选「开启回源鉴权」，否则 CDN 无法穿透 COS 的权限校验
- CDN 侧上传的 SSL 证书，内容必须包含完整证书链 —— 即
cert.pem+chain.pem拼接，漏掉 chain 会导致浏览器报ERR_CERT_AUTHORITY_INVALID - CDN 域名的 CNAME 解析生效后，COS 对象 URL 要从
https://bucket-125xxx.cos.ap-guangzhou.myqcloud.com切成https://cdn.yourdomain.com，否则加速无效
真正麻烦的不是写几行上传代码，而是 Region、key 编码、CDN 回源、证书链这四个点任意一个没对齐，错误信息都藏得深，日志里只显示 generic error。建议第一次调试时打开 SetDebugLog(true)，盯着控制台输出的原始 HTTP 请求头和响应状态码看。
