七牛云 Go SDK v7 必须使用 github.com/qiniu/go-sdk/v7 路径，旧版 qiniupkg/storage 已废弃；bucket 名需符合小写字母、数字、中划线且字母开头；上传需正确生成 token 并匹配区域域名。
七牛云 Go SDK 初始化报错 qiniupkg/storage 找不到
Go 模块管理下，官方 SDK 已迁移到 github.com/qiniu/go-sdk/v7，旧路径 qiniupkg/storage 是 v6 及更早版本的导入路径，v7 起必须用新包名，否则 go build 直接失败。
- 执行
go get github.com/qiniu/go-sdk/v7@latest安装最新版（注意带v7） - 代码中 import 必须写成
"github.com/qiniu/go-sdk/v7/auth/qbox"和"github.com/qiniu/go-sdk/v7/storage"，不能漏掉v7 - 如果项目用了 go mod tidy 但依然报错，检查
go.mod中是否残留了旧版依赖（如qiniupkg/storage v1.0.0），手动删掉并重跑go mod tidy
上传文件时提示 invalid bucket name 或 401 Unauthorized
这两个错误高频共存：前者是配置了非法空间名（比如含下划线、大写字母或长度超 32 字符），后者多因凭证过期、AK/SK 错位，或未正确生成 token。
- bucket 名只允许小写字母、数字、中划线，且必须以字母开头，例如
my-app-bucket合法，My_Bucket和123test都非法 - 确认
accessKey和secretKey是「密钥管理」页拿到的，不是「对象存储」控制台里的「AccessKey ID」别名 - 上传前必须调用
putPolicy.PutPolicy()生成上传凭证（token），不能直接把 AK/SK 当 token 传；v7 中推荐用storage.PutPolicy{Scope: "your-bucket:your-key"}.UploadToken(mac)
storage.PutFile 上传成功但文件内容为空或损坏
常见于未关闭文件句柄、或传入了已读完的 *os.File，SDK 内部读取时返回 EOF，导致上传空内容。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 确保传给
PutFile的filePath是本地完整路径（如"./data/photo.jpg"），不是相对路径片段 - 如果自己构造
io.Reader（比如从 HTTP body 读），务必确认 reader 可重放；不可复用已读取过的bytes.Buffer或http.Request.Body - 上传大文件（>100MB）建议改用
storage.PutFile的分片上传模式（设置opts = &storage.PutFileOptions{PartSize: 4 * 1024 * 1024}），否则内存暴涨且易超时
删除或更新文件时返回 no such file，但控制台能看见
本质是域名和区域不匹配：七牛云不同区域（华东、华北、华南等）有独立 API 域名，删/查操作必须与上传时使用的域名一致，否则跨区查不到。
立即学习“go语言免费学习笔记（深入）”；
- 上传用的是
https://upload-z1.qiniup.com（华东），那么删除也得走https://rs-z1.qiniup.com，不能混用rs-z2（华北） - 初始化
bucketManager时，必须显式指定cfg := storage.Config{Zone: &storage.ZoneZ1}，不能依赖默认值；ZoneZ1对应华东，ZoneZ2对应华北 - 若不确定空间所在区域，登录七牛控制台 → 空间设置 → 基本信息 → 查看「区域」字段，再选对应
Zone常量
实际写业务时，最容易被绕进去的是区域配置和 token 生成逻辑——它们不出现在上传主流程里，但一旦错一个字符，错误信息就非常模糊。建议把 mac、cfg、bucketManager 封装成单例，避免每次上传都重复构造。
