If-Range

用法

客户端在恢复部分下载或从此前获取的资源中提取特定字节范围时使用 If-Range。该头携带一个 ETag 值或一个 Last-Modified 日期作为验证器。每个请求只允许使用其中一种形式。

它与 If-Match 的关键区别在于条件失败时的行为。If-Match 失败会产生 412 Precondition Failed 错误并中止请求。而 If-Range 失败则会优雅地成功：服务器忽略 Range 头并以 200 状态返回整个资源。这使得 If-Range 对下载续传更安全，因为客户端总能收到可用的数据。

带 If-Range 的条件请求要求同一请求中包含 Range 头。若没有 Range 头，服务器会完全忽略 If-Range。

entity-tag

此前从服务器收到的 ETag 值。该值是一个带引号的字符串，且必须是强验证器：以 W/ 为前缀的弱 ETag 不允许用于 If-Range。

If-Range: "abc123"

HTTP-date

采用标准 HTTP 日期格式的 Last-Modified 时间戳。服务器将该日期与资源当前的修改日期进行比较。

If-Range: Wed, 01 Jun 2022 08:00:00 GMT

注意

If-Range 头携带一个 ETag 或一个日期。同一请求中不允许同时使用两种形式。

示例

客户端此前下载了大文件的一部分，并随初始响应收到了一个 ETag。为从第 1048576 字节处恢复下载，客户端同时发送 Range 头和携带已存储 ETag 的 If-Range 头。如果文件未发生变化，服务器以 206 Partial Content 响应。

GET /releases/archive.tar.gz HTTP/1.1
Host: cdn.example.re
Range: bytes=1048576-
If-Range: "a1b2c3d4e5"

当资源自初始下载以来已发生变化时，ETag 不再匹配。服务器丢弃 Range 并以 200 状态返回完整文件。

HTTP/1.1 200 OK
Content-Length: 52428800
ETag: "f6g7h8i9j0"

基于日期的验证器以相同方式工作。此请求仅在文件自指定时间戳以来未被修改时才恢复下载。

GET /data/export.csv HTTP/1.1
Host: api.example.re
Range: bytes=524288-
If-Range: Sat, 15 Feb 2025 12:00:00 GMT