用 AWS SDK v2 直连腾讯云 COS 是可行的，关键在于正确配置 endpoint（含 bucket 名）、region、signingName="cos" 和 ResolveUnknownService=true；上传应直接流式 PutObject，避免本地落盘；URL 拼接需匹配 region 且用外网域名，Key 需 URL 编码，上传后建议 HeadObject 校验可达性。
用 aws-sdk-go-v2/service/s3 直连 COS，不是换 SDK，是换配置
Gin 本身不处理云存储，它只负责接收 multipart/form-data 文件流。真正把文件“存到 COS”这件事，得靠 AWS SDK v2 的 s3.Client —— 腾讯云 COS 兼容 S3 协议，只要 endpoint、region、signingName 配对正确，签名就能过。官方 cos-go-sdk-v5 不是必须的，反而容易因协议细节（比如 ListObjectsV2 的 delimiter 行为、ETag 计算）出问题。
关键配置项必须显式指定：
-
endpoint必须是https://<bucket-name>.cos.<region>.myqcloud.com（注意不是cos.<region>.myqcloud.com，少<bucket-name>.就 404） -
region必须填真实地域缩写，如ap-beijing、ap-guangzhou，不能填cn-bj或空字符串 -
signingName必须设为"cos"，否则 SDK 默认用"s3"签名，COS 拒绝 - 必须启用
ResolveUnknownService: true，否则 SDK 因不认识cos服务名直接 panic
Gin 中上传流程：FormFile → 读取字节 → PutObject
不要用 c.SaveUploadedFile() 先存本地再传 COS，既浪费 IO 又多一层临时文件管理。应该直接从 *multipart.FileHeader 打开流，交给 s3.PutObject。
典型代码片段（省略错误处理）：
file, _ := c.FormFile("file")
src, _ := file.Open()
defer src.Close()
_, err := client.PutObject(ctx, &s3.PutObjectInput{
Bucket: aws.String("your-bucket-name"),
Key: aws.String("uploads/" + file.Filename),
Body: src,
ACL: types.ObjectCannedACLPublicRead, // 如需公开访问
})
注意点：
-
Key是 COS 中的路径，不能以/开头；建议加前缀（如uploads/）避免根目录混乱 - 如果要支持大文件（>5MB），需改用
CreateMultipartUpload+ 分片上传，PutObject有 5GB 上限且内存占用高 -
ACL: public-read仅当 bucket 权限允许时才生效；更安全的做法是生成预签名 URL 或走 CDN 域名 + referer 白名单
为什么 NotFound: The specified bucket does not exist 总是出现
这个错误 90% 不是 bucket 真不存在，而是 region 和 endpoint 映射错位。例如：
腾讯云通用文字识别（高精度版）技能包。用户发送/粘贴图片、提供图片URL或要求识别图片文字时自动调用。支持中文、英文、中英混合、数字及特殊符号的检测与识别，返回文字框位置与内容。适用于文字较多、版式复杂、准召率要求高的场景。
- bucket 在
ap-beijing，但配置了region = "ap-shanghai"→ endpoint 解析成https://xxx.cos.ap-shanghai.myqcloud.com→ 404 - endpoint 写成
https://cos.ap-beijing.myqcloud.com（漏掉 bucket 名）→ COS 认为请求的是 service-level 接口，不是 bucket-level，直接拒 - 用了
aws.Region自动解析（如config.WithRegion("ap-beijing")），但没关掉自动 region 推导 → SDK 仍尝试向https://s3.ap-beijing.amazonaws.com发请求
验证方法：把最终发出的 HTTP 请求 URL 打印出来，看是否形如 https://your-bucket.cos.ap-beijing.myqcloud.com/xxx。不是这个格式，就立刻检查 endpoint 字符串拼接逻辑。
上传后返回的 URL 怎么拼才对
COS 控制台里看到的“访问域名”分两种：内网（xxx.cos-internal.ap-beijing.myqcloud.com）和外网（xxx.cos.ap-beijing.myqcloud.com）。Gin 后端返回给前端的 URL 必须用外网域名，且不带协议头 —— 因为前端可能走 HTTPS 页面，混用 HTTP 会触发浏览器阻断。
正确拼法：
func cosObjectURL(bucket, key string) string {
return "https://" + bucket + ".cos." + os.Getenv("COS_REGION") + ".myqcloud.com/" + key
}
注意：
- 别硬编码
https://后面的 host，region 必须和初始化 client 时一致，否则签名和访问域名不匹配 - 如果启用了 CDN 加速，应返回 CDN 域名（如
https://cdn.example.com/uploads/xxx.jpg），而非 COS 原生域名 - Key 中的中文或特殊字符必须被 URL 编码，否则前端
<img src="...">会 400
最易忽略的一点：COS 的 PutObject 成功只代表文件已写入，不代表立即可读 —— 如果开了版本控制或跨区域复制，可能有秒级延迟。生产环境建议上传后用 HeadObject 主动探活，而不是盲目返回 URL。
