七牛云 SDK 初始化需用 github.com/qiniu/go-sdk/v7@latest，导入路径含/v7；上传凭证须用 PutPolicyV2+SignV2 生成；PutFile 要传绝对路径或文件句柄；并发上传需限流并显式配置 Zone、UseHTTPS。
七牛云 SDK 初始化报错 qiniupkg/storage 找不到
Go 模块初始化没拉对包，常见于直接 go get github.com/qiniu/api.v7 这种旧路径。新版 SDK 已迁移到 github.com/qiniu/go-sdk/v7，且必须用 v7 后缀——v6 或无版本号会导入失败或编译不通过。
实操建议：
- 运行
go get github.com/qiniu/go-sdk/v7@latest，确保go.mod里出现github.com/qiniu/go-sdk/v7 v7.x.x - 导入时写
import "github.com/qiniu/go-sdk/v7/auth/qbox"和"github.com/qiniu/go-sdk/v7/storage"，不能漏掉/v7 - 如果还在用
qiniupkg/storage，说明混用了社区 fork 的非官方包，立即删掉，它不维护、不兼容新鉴权逻辑
上传文件时提示 invalid bucket name 或 401 Unauthorized
不是 bucket 名写错了，就是 token 过期或权限不对。七牛云的 PutPolicy（旧版）已弃用，现在必须用 PutPolicyV2 + SignV2 生成 token，否则哪怕 AK/SK 正确也会 401。
实操建议：
- 确认 bucket 名是创建时填的「空间名」（如
my-app-2024），不是控制台显示的「空间域名」或「外链地址」 - 生成上传凭证必须用
mac := qbox.NewMac(ak, sk)+putPolicy := storage.PutPolicyV2{Scope: "my-app-2024"}+token, _ := putPolicy.UploadToken(mac) - 不要手拼 token 字符串，也不要复用超过 3600 秒的 token，七牛服务端强制校验有效期
storage.PutFile 传本地路径失败，但 Put 可以
PutFile 要求第一个参数是本地绝对路径或可读的文件句柄，但它内部会调用 os.Open，如果路径含中文、空格或符号（如 ~/Downloads/test.png），就直接 panic 或返回 file does not exist。
实操建议：
- 用
filepath.Abs转成绝对路径再传给PutFile，别信相对路径 - 更稳的方式是自己
f, _ := os.Open("xxx.png")，然后调storage.Put，传f和f.Stat().Size() -
PutFile的key参数如果为空字符串，七牛会自动生成 hash 命名，但很多业务需要固定 key，记得显式传参
并发上传大量小文件时内存暴涨、GC 频繁
默认 storage.Config 里 Zone 是 ZoneHuadong（华东），但没设 UseHTTPS 和 UseCdnDomains，SDK 会反复建连接、缓存响应体，加上默认 PutFile 内部用 io.Copy 读全文件进内存，小文件多时 GC 压力明显。
实操建议：
- 显式配置
cfg := storage.Config{Zone: &storage.ZoneHuadong, UseHTTPS: true, UseCdnDomains: false} - 上传前用
file, _ := os.Open(path)+stat, _ := file.Stat()，把file和stat.Size()传给Put，避免PutFile多一次os.Open - 并发控制别直接开 100 goroutine，用
semaphore或带缓冲 channel 限流到 5–10，七牛单个账号有 QPS 限制，超了反而 429
七牛的上传凭证和区域配置不是“设一次就完事”，每次上传都可能因 bucket 归属地不同而走错机房；token 生效前最好先 curl -v 测下上传地址是否能连通，比盲传报错后再查快得多。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
