必须使用 go get github.com/qiniu/go-sdk/v7@latest 安装，禁用 qiniupkg/storage 和 github.com/qiniu/api.v7；导入路径、token 生成、区域配置、bucket 命名及上传方法均须严格匹配 v7 规范。
go get 安装必须带 /v7，否则编译失败
直接执行 go get github.com/qiniu/go-sdk/v7@latest，不是 github.com/qiniu/api.v7 也不是 qiniupkg/storage。后者已归档，v7 版本强制要求路径含 /v7，且模块名、导入路径、函数签名全部重构过。IDE 自动补全可能仍推旧包，必须手敲完整路径。
检查 go.mod：若存在 qiniupkg/storage 或 github.com/qiniu/api.v7，手动删掉整行，再运行 go mod tidy。残留旧依赖会导致 import "github.com/qiniu/go-sdk/v7/auth" 报错找不到包。
UploadToken 必须绑定 bucket 和显式 Zone
token 不是通用凭证，Scope 字段必须写成 "your-bucket-name"（不能带域名或 key），且初始化 storage.Config 时必须传 &storage.ZoneHuadong 这类具体区域指针——不能靠自动探测，尤其在 Docker、内网或代理环境下会默认为 ZoneZ0 导致上传返回 401 Unauthorized 或 invalid bucket name。
bucket 名需满足：小写字母开头、只含小写字母、数字、中划线（如 my-app-2026），不能有下划线、大写、点号或空格；长度不超过 32 字符。拼错一个字符，token 生效但上传必报错。
PutFile 和 Put 别混用，参数类型完全不同
uploader.PutFile 接收本地文件路径字符串（如 "./uploads/photo.jpg"），内部打开并流式读取；uploader.Put 只接收 []byte 或实现了 io.Reader 的对象（如 bytes.NewReader(data)）。常见错误是把路径字符串传给 Put，结果上传内容变成路径文本本身。
- 上传磁盘文件：
uploader.PutFile(ctx, &ret, token, key, filePath, nil) - 上传内存数据（如
c.Request.FormFile后读出的[]byte）：uploader.Put(ctx, &ret, token, key, data, nil) -
ctx建议带超时：context.WithTimeout(context.Background(), 30*time.Second)，避免大文件卡死无响应
删除/查询操作必须和上传使用同一区域域名
上传走 https://upload-z1.qiniup.com（华东），那么 BucketManager 初始化时 cfg 的 APIHost 也得设为 https://rs-z1.qiniup.com。混用 rs-z2（华北）会导致 no such file，即使控制台能看见文件——本质是跨区隔离，不是权限或路径问题。
公有 URL 构建也需匹配：华东 bucket 对应域名后缀是 .z1.qiniup.com，华北是 .z2.qiniup.com，私有 bucket 还要加过期时间签名校验。别拿上传用的 token 直接拼 URL，那是临时凭证，不是访问地址。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
