C#调用Dropbox API下载文件教程

Dropbox API v2 下载文件必须使用 FilesDownloadAsync，它返回 FilesDownloadResponse 并通过 GetContentAsStreamAsync() 流式获取数据；禁用 FilesGetTemporaryLinkAsync，因其需手动处理重定向、过期和认证，且易出错。

Dropbox API v2 下载文件必须用 FilesDownloadAsync，别碰 FilesGetTemporaryLinkAsync

Dropbox 官方 v2 SDK 不提供直接返回文件流的“下载方法”，FilesDownloadAsync 是唯一正解。它返回 FilesDownloadResponse，其中 GetContentAsStreamAsync() 才真正拉取二进制数据。有人误用 FilesGetTemporaryLinkAsync 拿到一个带签名的 HTTP 链接再自己发 GET 请求——这不仅多一次网络跳转、容易因链接过期失败，还绕过了 SDK 的自动重试和错误解析。

常见错误现象：HttpRequestException: Response status code does not indicate success: 401 (Unauthorized) 或空流，往往是因为用了临时链接但没处理重定向/没传 Authorization header。

• FilesDownloadAsync 自动处理认证头、重试、429 限流响应
• 返回的 FilesDownloadResponse 包含元数据（如 ServerModified、Size），可用于校验
• 临时链接方式需额外处理 302 重定向，且链接默认 4 小时失效，不适合后台长期任务

下载大文件时必须用 GetContentAsStreamAsync() + 流式写入，禁止 ToArray() 或 ReadAllBytesAsync()

Dropbox 文件可能几百 MB 甚至上 GB。GetContentAsStreamAsync() 返回的是一个可 await 的 Task<Stream>，它底层是 HTTP 响应流，不缓冲全量内容。如果调用 await stream.ReadAsByteArrayAsync() 或 await stream.ToArray()，会把整个文件加载进内存，极易触发 OutOfMemoryException。

正确做法是边读边写：

using var response = await client.Files.DownloadAsync("/report.xlsx");
using var stream = await response.GetContentAsStreamAsync();
using var fileStream = File.Create(@"C:\temp\report.xlsx");
await stream.CopyToAsync(fileStream);

• 始终用 CopyToAsync 或分块 ReadAsync/WriteAsync，避免内存暴涨
• 若需校验 SHA-256，可在 Copy 过程中用 CryptoStream 计算，无需额外加载
• 注意：response.ContentHash 是 Dropbox 计算的校验值（RFC 3161 格式），不是原始文件哈希，不能直接比对

路径参数必须是绝对路径，开头带 /，且不能包含 URL 编码字符

Dropbox API 要求 path 参数是服务器端路径，格式为 /Documents/photo.jpg。传 "Documents/photo.jpg"（缺开头 /）会报错 ApiException: path: malformed_path/"path"；传 "/Documents/my%20file.pdf"（手动编码）则返回 409 PathRootError.MalformedPath —— SDK 内部已自动 URL 编码，你传原始 Unicode 字符即可。

• 正确："/Backup/财务报表 Q3.xlsx"（中文路径直接传）
• 错误："Backup/财务报表 Q3.xlsx"（缺 /）、"/Backup/%E8%B4%A2%E5%8A%A1%E6%8A%A5%E8%A1%A8.xlsx"（重复编码）
• 若路径来自用户输入，先用 Path.GetFileName 提取文件名，再拼到目标目录下，避免注入上级目录（如 "../etc/passwd"）

409 PathNotFound 错误的三个真实原因和检查顺序

遇到 ApiException 带 PathNotFound，别急着重试。90% 是以下三种情况之一，按此顺序排查最省时间：

• 文件确实不存在：用 Dropbox 网页端确认路径和大小写（Linux 风格，Report.pdf ≠ report.pdf）
• App 权限不足：在 Dropbox App Console 查看该 app 的「Permissions」，确保勾选了 files.content.read（只读）或 files.content.write（读写）
• Token 绑定错了账户：用 Auth.TokenFromOAuth2CodeAsync 获取 token 时，确认授权页面登录的是目标账号；或调用 Users.GetCurrentAccountAsync() 对比 AccountId 是否匹配预期

Dropbox 的路径语义和本地文件系统不同：没有“当前工作目录”概念，所有路径都从根开始；也没有符号链接或硬链接支持。最稳妥的做法是，先用 FilesListFolderAsync 列出父目录，确认文件名精确匹配后再下载。