PHP断点续传远程文件的核心是使用curl_setopt($ch, CURLOPT_RESUME_FROM, $offset)设置起始偏移，而非仅靠手动添加Range头；需配合fopen('c')、CURLOPT_BINARYTRANSFER和服务器支持Accept-Ranges: bytes。
PHP 用 cURL 断点续传远程文件的关键是 Range 请求头
断点续传不是靠“记住上次下载到哪”，而是靠 HTTP 协议的 Range 头告诉服务器“我要从第 N 字节开始拿”。PHP 的 curl_setopt() 必须显式设置，否则默认全量下载，curl 不会自动识别或恢复。
- 先用
file_exists()和filesize()检查本地文件是否存在及大小 - 若存在且非空，计算起始偏移：
$resume_from = filesize($local_file) - 必须调用
curl_setopt($ch, CURLOPT_RESUME_FROM, $resume_from)—— 这是核心，不是可选 - 不能只靠
Range: bytes=$resume_from-手动设头：某些服务器（如 Nginx 默认配置）不响应自定义 Range，但认CURLOPT_RESUME_FROM；而 Apache 可能两者都支持，但 PHP cURL 封装层更可靠
断点续传失败的常见现象和排查点
下载后文件大小不变、重复写入开头、返回 416 Requested Range Not Satisfiable 或直接 200 但内容重头开始——这些都不是代码逻辑错，而是服务端或请求配置没对齐。
-
416错误：说明服务器收到 Range，但认为请求范围越界。检查远程文件是否被删/改过，或$resume_from算错（比如文件被其他进程截断过） - 返回完整文件（200 + 全量 body）：服务器忽略 Range，常见于静态文件托管未启用 byte-range 支持（如部分 CDN、OSS 默认关 Range）
- 本地文件越下越大但内容错乱：没加
curl_setopt($ch, CURLOPT_BINARYTRANSFER, true)，导致文本模式换行符被 PHP 自动转换 - 没写入任何内容：忘了
curl_setopt($ch, CURLOPT_FILE, $fp)，或fopen()用了'w'而非'c'（'c'是关键：打开并允许追加，不截断）
完整可运行的断点续传示例（含错误防护）
以下代码处理了文件打开、Range 设置、流写入、连接异常重试等真实场景需要的细节，不是玩具 demo。
function download_with_resume($url, $local_file) {
$fp = fopen($local_file, 'c');
if (!$fp) {
throw new Exception("Cannot open $local_file for writing");
}
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, false);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_BINARYTRANSFER, true);
curl_setopt($ch, CURLOPT_FILE, $fp);
// 启用断点：仅当本地文件存在且非空时才设置
if (file_exists($local_file) && ($size = filesize($local_file)) > 0) {
curl_setopt($ch, CURLOPT_RESUME_FROM, $size);
}
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);
fclose($fp);
if ($result === false || $http_code >= 400) {
throw new Exception("cURL failed: $error (HTTP $http_code)");
}
}
注意服务器端是否真正支持 Range
客户端设了 CURLOPT_RESUME_FROM，不代表一定能续传。最终取决于远程服务是否返回 Accept-Ranges: bytes 响应头，并正确处理 Range 请求。
立即学习“PHP免费学习笔记（深入）”；
- 用
curl -I $url查看响应头，确认有Accept-Ranges: bytes - 常见不支持场景：PHP 脚本动态输出文件（如
readfile()）、部分对象存储的私有 URL（需签名且签名不含 Range）、Nginx 未开启enable_ranges on; - 如果服务器不支持，唯一办法是重新下载，或换用支持分片下载的协议（如 FTP、SFTP），但那就不是 HTTP 断点续传了
断点续传真正的难点不在 PHP 侧，而在确认并验证远端 HTTP 服务的行为是否符合 RFC 7233。别把问题归给 curl_setopt 没设对，先抓包看它发了什么、对方回了什么。
