必须由后端生成uploadToken，不能暴露AccessKey/SecretKey；Token含签名、时效与策略，前端仅需uptoken和domain，上传时需正确配置token字段与上传域名。
前端直传七牛云，必须由后端生成合法的 uploadToken，否则上传会返回 401 Unauthorized 或 invalid token 错误。这个 Token 不是静态密钥，而是带签名、有时效、可约束策略的一次性凭证。
为什么不能直接把 AccessKey/SecretKey 丢给前端
这是最常踩的坑：把 accessKey 和 secretKey 硬编码在前端或接口响应里，等于把云存储控制权拱手让人。七牛服务端校验时只认 uploadToken，它由后端用 Auth.create(accessKey, secretKey) 签发，含过期时间、bucket 限制、回调地址等策略。暴露原始密钥会导致任意文件上传、删除、甚至 bucket 清空。
- 前端拿到的只能是
uploadToken字符串，长度约 200+ 字符，形如xxx:yyy:zzz - Token 过期后前端需重新请求接口，不能缓存复用
- 若需限制上传路径（如只允许
avatar/下），必须在签发时通过putPolicy指定scope和saveKey
Go SDK v7 的 uploadToken 签发要点
Gin 中调用七牛 Go SDK v7 生成 Token，核心是 auth.UploadToken(bucket, key, putPolicy)。注意 v7 已弃用旧版 api.v7，必须用 github.com/qiniu/go-sdk/v7。
-
bucket必须与你在七牛控制台创建的存储空间名完全一致（区分大小写） -
key可设为""（允许客户端指定文件名）或固定值（如"temp/" + uuid.New().String()） -
putPolicy是个 struct，关键字段：Scope（"bucket:key"格式）、Expires（秒级，建议 ≤ 3600）、CallbackUrl（可选，用于上传完成回调） - 别漏掉
Region配置，华东机房用Region.Region0()，华北用Region.Region1()，否则可能报invalid region
Gin 路由 handler 返回 JSON 的实操写法
接口设计要轻量，只返回必需字段。前端只需要 uptoken 和 domain（即七牛绑定的自定义域名或默认域名），其他如 bucket、expireAt 属于冗余信息。
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
立即学习“前端免费学习笔记（深入）”；
func getUploadToken(c *gin.Context) {
bucket := "your-bucket-name"
domain := "https://your-domain.qiniup.com"
putPolicy := storage.PutPolicy{
Scope: bucket,
Expires: 1800, // 30 分钟
}
uptoken := auth.UploadToken(bucket, "", &putPolicy)
c.JSON(http.StatusOK, gin.H{
"uptoken": uptoken,
"domain": domain,
})
}
- 路由注册：
r.GET("/api/upload/token", getUploadToken) - 不要在响应里塞
accessKey或secretKey—— 即使加了omitempty也危险 - 如果前端需要指定文件名（如用户头像），让前端在表单中传
key字段，后端签发时key设为空即可
前端直传时容易忽略的两个细节
拿到 uptoken 后，前端用 qiniu-js 或原生 FormData 上传，但以下两点不处理就会卡在 pending 或 400：
- 表单必须带
token字段，值为后端返回的uptoken；若用qiniu-js，new Qiniu.Uploader({ uptoken: "...", ... })里的字段名是uptoken，不是token - 上传域名必须用
domain（如https://upload.qiniup.com或你绑定的https://up.yourdomain.com），不能拼错成https://your-bucket-name.qiniu.com—— 这个错误导致 404 最常见
Token 的有效期和策略约束是动态的，每次上传前都该走一遍后端签发流程，而不是前端自己算 —— 算错了就废，而且私钥绝不能出服务端边界。
