Go调用七牛云上传失败主因是token生成、cfg配置及PutFile参数错误；PutFile不校验token和路径，401/403时err为nil而ret.Key为空；须检查ret.Key非空、Zone需匹配bucket区域、大文件用Put、token须动态生成且防泄露。
Go 语言调用七牛云上传，核心不是“会不会写”，而是“token 怎么生成、cfg 怎么配、PutFile 里哪个参数填错就静默失败”——绝大多数上传失败都卡在这三处。
为什么 PutFile 返回 nil 错误却没上传成功？
这是最常被忽略的陷阱：七牛云 SDK 的 PutFile 不校验 token 有效性，也不主动检查文件路径是否存在。它只管发请求，服务端拒收时返回的是 HTTP 401/403，但 SDK 默认把这类响应转成 err == nil，只把 ret.Key 置空或留空字符串。
-
upToken过期或签名错误 → 服务端返回 401，err为nil，ret.Key为空 -
filePath是相对路径且当前工作目录不对 →os.Open失败，err才非nil（但很多人没打印err） -
key含非法字符（如\、控制符）→ 上传被拦截，ret.Key为空，无报错提示
实操建议：每次上传后必须显式检查 ret.Key != ""，不能只看 err == nil。
storage.Config 的 Zone 字段不设会怎样？
不设 Zone 会导致 SDK 自动 fallback 到默认区域（通常是华东），但如果 bucket 实际在华北或华南，上传请求会被转发，增加延迟，极端情况下触发跨区限流，返回 503 或超时。
立即学习“go语言免费学习笔记（深入）”；
- 华东 bucket → 用
&storage.ZoneHuadong - 华北 bucket → 用
&storage.ZoneHuabei - 华南 bucket → 用
&storage.ZoneHuanan - 不确定区域？别猜，登录七牛云控制台，进 bucket 设置页看「存储区域」字段
注意：storage.ZoneAuto 已废弃，新版 SDK 不识别；硬写错 Zone 名（如 ZoneEastChina）会导致编译失败。
上传大文件时，PutFile 和 Put 该选哪个？
PutFile 是封装好的文件路径上传，适合小文件（Put 接收 io.Reader，适合内存流、分块读取或需要自定义进度回调的场景。
- 上传本地磁盘文件，路径确定 → 用
PutFile，简单直接 - 上传 HTTP 请求体（如 Gin 中的
c.FormFile）、加密后字节流、或需要断点续传 → 必须用Put，传fileContent或bytes.NewReader(data) -
PutFile内部仍会打开文件并读全量到内存再发，对 >100MB 文件可能 OOM；Put可配合bufio.Reader控制缓冲区大小
示例关键区别：
err := formUploader.PutFile(ctx, &ret, upToken, key, "/tmp/a.jpg", nil) // ✅ 路径 err := formUploader.Put(ctx, &ret, upToken, key, fileContent, nil) // ✅ Reader
如何避免 uploadToken 泄露或复用过期？
token 不是长期凭证，有效期由 PutPolicy.Expires 控制（默认 3600 秒）。硬编码或全局缓存 token 是高危操作。
- 每个上传请求前动态生成 token，哪怕同一秒内多次上传也重新算
- 不要把
upToken存数据库或日志（它含密钥签名，泄露等于密钥泄露） - 如果需支持前端直传，务必用后端签发 + 指定
Scope（如bucket:key），禁用宽泛 scope（如仅bucket） - 调试时打印 token 前先截断中间段，例如
fmt.Printf("upToken: %s...%s\n", token[:8], token[len(token)-8:])
真正容易被忽略的点：token 签名依赖系统时间，如果服务器时间偏差 >15 分钟，token 会直接被七牛云拒绝，且错误信息极其模糊（常表现为 401 + 空 ret）。务必确认 NTP 同步正常。
