应使用 github.com/qiniu/go-sdk/v7,禁用 qiniupkg/storage 和 github.com/qiniu/api.v7;导入路径须含 /v7,token 生成需绑定 bucket 名与区域,上传用 PutFile/Put 区分文件与内存数据,公私有 URL 构建须匹配域名后缀与区域。

直接用 github.com/qiniu/go-sdk/v7,别碰 qiniupkg/storage 或 github.com/qiniu/api.v7 —— 后者已过时且不兼容 v7 的模块路径和 API 设计,go build 会报错找不到包。
导入路径和模块初始化必须带 v7
v7 是语义化版本强制要求,不是可选后缀。旧教程里写的 github.com/qiniu/api.v7 看似带 v7,实为历史遗留别名,官方早已归档;当前唯一支持的路径是 github.com/qiniu/go-sdk/v7。
- 执行
go get github.com/qiniu/go-sdk/v7@latest安装(注意末尾@latest和路径中/v7) -
import语句必须写成:"github.com/qiniu/go-sdk/v7/auth"、"github.com/qiniu/go-sdk/v7/storage"、"github.com/qiniu/go-sdk/v7/storage/putpolicy" - 检查
go.mod:若存在qiniupkg/storage或github.com/qiniu/api.v7,手动删掉整行,再跑go mod tidy - IDE 自动补全可能仍推旧包,务必手敲 v7 路径,别依赖提示
上传 token 生成必须绑定 bucket 和区域
token 不是通用凭证,它和 bucket 名、所在区域强绑定。用错区域或拼错 bucket 名,上传必然返回 401 Unauthorized 或 invalid bucket name。
- bucket 名必须小写字母开头,只含小写字母、数字、中划线(如
my-app-bucket),不能有下划线或大写 - 区域必须显式指定,例如华东是
storage.ZoneHuadong,华北是storage.ZoneHuabei,不能靠自动探测(尤其私有网络或代理环境下会失败) - 生成 token 时要传
PutPolicy{Scope: "your-bucket-name"},不能只传文件 key - 示例关键片段:
mac := auth.New(accessKey, secretKey) cfg := storage.Config{Zone: &storage.ZoneHuadong} putPolicy := putpolicy.PutPolicy{Scope: "my-bucket-name"} token := putPolicy.UploadToken(mac)
上传文件必须用 FormUploader.PutFile 或 Put,别混用旧版接口
v7 中 storage.Uploader 已移除,Put 方法只接受 []byte,而 PutFile 才支持本地路径字符串。常见错误是拿 Put 直接传文件路径字符串,结果上传的是路径文本本身。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器,提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象,支持命名依赖等
- 传内存数据(如 HTTP body):用
uploader.Put(ctx, &ret, token, key, data, nil) - 传磁盘文件:用
uploader.PutFile(ctx, &ret, token, key, filePath, nil) -
ctx建议传带 timeout 的 context,避免上传卡死无响应 - 上传后检查
ret.Key和ret.Hash,不是所有失败都会触发err != nil(比如部分元数据写入失败)
公有/私有资源访问 URL 构建容易忽略域名和权限匹配
公开空间的 URL 是纯拼接,但私有空间必须签算 deadline 参数,且域名必须和 bucket 绑定的「默认域名」一致——控制台里填的是 xxx.qiniucs.com,代码里却用了 xxx.qiniu.com,就会 403。
- 公开 URL:
storage.MakePublicURL("https://your-bucket.z0.qiniup.com", "file.jpg") - 私有 URL:
storage.MakePrivateURL(mac, "https://your-bucket.z0.qiniup.com", "file.jpg", time.Now().Add(2*time.Hour).Unix()) - 域名后缀必须和 bucket 所在区域严格对应:华东是
z0,华北是z1,华南是z2,北美是na0 - 私有 URL 的
deadline是 Unix 秒级时间戳,不是毫秒,别用time.Now().UnixMilli()
最常被跳过的点:区域配置和域名后缀必须一一对应,改了 bucket 区域却不改 Zone 变量或 URL 域名,问题会静默出现在生产环境,而不是本地测试阶段。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!










