本文详解 php 调用 dropbox v2 api 下载远程文件到本地服务器的完整实现，指出常见错误（如错误的 post 设置、缺失 json 编码头、未处理二进制响应），并提供可直接运行的健壮代码示例。
本文详解 php 调用 dropbox v2 api 下载远程文件到本地服务器的完整实现，指出常见错误（如错误的 post 设置、缺失 json 编码头、未处理二进制响应），并提供可直接运行的健壮代码示例。
Dropbox API v2 的 /files/download 接口要求严格遵循 REST 规范：它是一个 GET 请求（非 POST），且必须通过 Dropbox-API-Arg 请求头传递 JSON 格式的路径参数，同时需正确处理二进制响应流——这是原代码失败的核心原因。
首先，CURLOPT_POST = TRUE 是错误的：该接口不接受 POST 方法，而应使用 GET（cURL 默认即为 GET，显式设为 POST 会触发 405 Method Not Allowed 错误）。其次，CURLOPT_FILE 虽可用于流式写入，但若未设置 CURLOPT_BINARYTRANSFER = true 且未禁用 CURLOPT_RETURNTRANSFER 冲突，极易导致内容截断或乱码；更稳妥的做法是获取原始二进制响应后手动写入文件。
✅ 正确实现如下（含错误处理与健壮性增强）：
<?php
$access_token = 'YOUR_ACCESS_TOKEN';
$filepath = '/Reports/quarterly.pdf'; // Dropbox 中的绝对路径（以 / 开头）
$local_filename = '/var/www/html/downloads/quarterly.pdf';
$url = 'https://content.dropboxapi.com/2/files/download';
// 构建 Dropbox-API-Arg 头（必须 JSON 编码且无空格）
$api_arg = json_encode(['path' => $filepath], JSON_UNESCAPED_SLASHES);
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_BINARYTRANSFER => true, // 关键：确保二进制安全
CURLOPT_HEADER => false,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$access_token}",
"Dropbox-API-Arg: {$api_arg}",
"Content-Type: application/octet-stream" // 显式声明，非必需但推荐
],
]);
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);
// 检查 HTTP 状态码
if ($http_code !== 200) {
throw new Exception("Dropbox API error: HTTP {$http_code} — " . ($error ?: 'Unknown error'));
}
// 确保目录存在
$dir = dirname($local_filename);
if (!is_dir($dir) && !mkdir($dir, 0755, true)) {
throw new Exception("Failed to create directory: {$dir}");
}
// 写入文件（使用 file_put_contents 更简洁可靠）
if (file_put_contents($local_filename, $response) === false) {
throw new Exception("Failed to write file to disk: {$local_filename}");
}
echo "✅ File downloaded successfully: {$local_filename}\n";
?>⚠️ 关键注意事项：
立即学习“PHP免费学习笔记（深入）”；
- 路径格式：$filepath 必须是 Dropbox 中的绝对路径（如 "/Documents/file.txt"），不能省略开头的 /；
- Token 权限：确保 access token 具有 files.content.read 权限；
- 文件大小：大文件建议改用 CURLOPT_FILE + fopen('w+b') 流式写入，避免内存溢出；
- 错误调试：临时添加 var_dump(curl_getinfo($ch)) 和检查 $response 是否为空，可快速定位网络或认证问题；
- 安全性：生产环境务必校验 $filepath，防止路径遍历攻击（例如拒绝 .. 字符）。
通过以上修正，即可稳定、高效地将 Dropbox 文件下载至 PHP 服务器本地磁盘。
