七牛云 SDK 初始化失败主因是版本错配：QiniuSDK 7.x 仅支持 .NET Framework 4.5+，不兼容 .NET Core/5+；应改用 Qiniu.CSharp.SDK 或 Qiniu.HttpClient + 手写签名。

七牛云 SDK 初始化失败：MissingMethodException 或 TypeLoadException

用 NuGet 安装 QiniuSDK 后，调用 Config 或 Auth 就崩，大概率是版本错配。官方 SDK（QiniuSDK 7.x）只支持 .NET Framework 4.5+，不兼容 .NET Core / .NET 5+ 项目。强行运行会抛 MissingMethodException: Method not found: 'System.Net.Http.HttpClient System.Net.Http.HttpClientFactory.Create()' 这类错误。

• 确认项目目标框架：若为 netcoreapp3.1、net6.0 或更高，**不要用 QiniuSDK**，改用官方维护的 Qiniu.HttpClient（仅含 HTTP 层） + 手写签名逻辑，或更推荐的社区适配版 Qiniu.CSharp.SDK（已迁移到 System.Net.Http）
• 若坚持用老 SDK，必须降级项目为 net461 或以上，并确保引用 System.Net.Http 4.3.4+ 版本
• Qiniu.CSharp.SDK 的初始化更干净：

  var auth = new Auth("your_access_key", "your_secret_key");
  var uploadManager = new UploadManager();

上传时提示 “invalid token” 或 401 Unauthorized

token 是临时凭证，由服务端生成后传给客户端，**绝不能把 secret_key 暴露在前端或客户端代码里**。C# 客户端直接拼 token 属于高危操作，常见于误抄旧教程。

• 正确流程：C# 后端生成上传凭证（auth.UploadToken(bucket, key, 3600)），返回给前端或移动端；客户端只拿这个 token 做上传
• 若确需 C# 客户端直传（如 WinForm 工具），token 必须由可信服务端接口下发，不能硬编码或本地计算
• 检查 bucket 名是否全小写、无下划线，且与 portal 中一致；key 若为 null，七牛默认使用文件 hash 命名，但 token 必须允许空 key：auth.UploadToken(bucket, null, 3600, new PutPolicy { InsertOnly = 0 })

大文件分片上传卡在 0% 或报 “request timeout”

默认的 UploadManager.Put 是简单上传，只适合 4MB 以下。超过阈值必须走 ResumeUpload，否则超时或内存爆掉。

C#

"避开 C# 常见错误——空陷阱、异步陷阱、LINQ 陷阱及资源泄漏。"

下载

• 启用断点续传需额外依赖 Qiniu.CSharp.SDK 的 ResumableUploadManager，并指定 ChunkSize（建议 4MB）和本地记录路径：

  var resumable = new ResumableUploadManager(
      new ResumeUploaderOptions { ChunkSize = 4 * 1024 * 1024 });
  resumable.PutFile(auth, bucket, key, localFilePath, null, null);

• 注意临时分片记录文件（.qiniuupload）默认存在系统临时目录，若多线程上传同文件，需手动指定唯一 RecordDirectory 避免冲突
• 内网上传（如服务器直传）可关 SSL 提速：Config.UseHttps = false，但仅限可信环境

上传成功但文件无法访问：HTTP 404 或 Content-Type 错乱

七牛默认不设 Content-Type，浏览器可能拒播视频/音频，或图片显示为下载。这不是 SDK bug，是元信息缺失。

• 上传时显式传入 PutExtra 设置 MIME：

  var extra = new PutExtra { MimeType = "image/png" };
  uploadManager.PutFile(auth, bucket, key, filePath, token, extra);

• 若用 PutBytes 传内存流，务必手动指定 MimeType，否则默认为 application/octet-stream
• CDN 缓存可能延迟生效，新上传文件首次访问 404 属正常，等 1–2 分钟或调用 RefreshUrls 主动刷新（需开通权限）

最易被忽略的是 token 生效范围和生命周期——哪怕参数全对，过期的 token 或限制了 key 前缀的策略也会静默失败。调试时优先抓包看请求 header 中的 Authorization 是否存在、是否被截断，比查 SDK 日志更快。