Python高效文件下载：分块传输与断点续传深度解析334

在日常的软件开发中，文件下载是一个极为常见的需求。无论是从远程服务器获取更新包、媒体文件，还是处理大数据集，高效且健壮的文件下载机制都是不可或缺的。对于Python开发者而言，`requests`库无疑是进行HTTP请求的首选工具。然而，当面对大型文件时，简单的全文件一次性下载方式可能会带来内存溢出、下载中断无法恢复等问题。本文将深入探讨Python中如何利用分块传输（Chunked Transfer）技术进行文件下载，并在此基础上实现断点续传功能，以提高下载的稳定性、效率和用户体验。

为何需要分块下载？

传统的下载方式通常是发送一个GET请求，服务器将整个文件数据一次性发送给客户端，客户端在内存中接收所有数据，然后写入磁盘。这种方式对于小文件来说没有问题，但对于GB甚至TB级别的大文件，它会带来几个显著的弊端：

内存溢出（MemoryError）： 将整个大文件加载到内存中会迅速耗尽系统资源，导致程序崩溃。
下载中断与重试困难： 如果网络不稳定或服务器连接中断，整个下载过程将失败，需要从头开始重新下载，浪费时间和带宽。
用户体验差： 无法实时显示下载进度，用户无法预估下载完成时间。
效率低下： 对于超大文件，一次性传输可能因为网络抖动或超时而更容易失败。

分块下载技术通过将文件数据分割成较小的、可管理的数据块（chunks）进行传输和处理，有效解决了上述问题。客户端每接收到一个数据块，就立即将其写入磁盘，然后请求下一个数据块。这种流式处理的方式，极大地降低了内存占用，并为实现进度显示和断点续传提供了基础。

Python `requests`库的分块下载核心

`requests`库提供了强大的功能来支持分块下载。关键在于设置`stream=True`参数和使用`iter_content()`方法。

1. 启用流式传输：`stream=True`

当你向`()`方法传递`stream=True`时，`requests`不会立即下载整个响应体。它只会下载HTTP响应头，并将连接保持开放，等待你逐块读取响应内容。这是实现分块下载的基石。
import requests
url = "/"
response = (url, stream=True)
# 此时，只有响应头被下载，响应体还在服务器端等待读取

2. 逐块读取内容：`iter_content()`

在`stream=True`模式下，`response`对象提供了`iter_content(chunk_size=...)`方法，它允许你以指定大小的数据块迭代读取响应内容。`chunk_size`参数定义了每个数据块的大小（字节）。一个常用的`chunk_size`值是8192字节（8KB），这在大多数情况下能提供良好的性能平衡。
import requests
import os
url = "/"
local_filename = ('/')[-1]
try:
with (url, stream=True) as r:
r.raise_for_status() # 检查HTTP响应状态码，如果不是2xx，则抛出异常
total_size = int(('content-length', 0)) # 获取文件总大小
with open(local_filename, 'wb') as f:
downloaded_size = 0
for chunk in r.iter_content(chunk_size=8192): # 每次迭代获取8KB数据
if chunk: # 过滤掉保持连接的空数据块
(chunk)
downloaded_size += len(chunk)
# 在这里可以更新下载进度条
# print(f"已下载: {downloaded_size}/{total_size} 字节")
except as e:
print(f"下载失败: {e}")
except Exception as e:
print(f"发生其他错误: {e}")
print(f"文件 {local_filename} 下载完成！")

这段代码展示了一个基本的循环，用于从响应中获取数据块并写入本地文件。它还包含了错误处理和获取文件总大小的逻辑，这对于进度显示至关重要。需要注意的是，`Content-Length`头可能并非在所有情况下都存在，或者可能不准确，特别是在使用`Transfer-Encoding: chunked`的动态内容时。

实现下载进度条

有了分块下载和文件总大小，实现一个可视化的下载进度条变得非常简单。`tqdm`是一个优秀的Python库，可以轻松地为循环添加进度条。
import requests
import os
from tqdm import tqdm # 导入tqdm
url = "/"
local_filename = ('/')[-1]
try:
with (url, stream=True) as r:
r.raise_for_status()
total_size = int(('content-length', 0))
# 使用tqdm包装文件写入操作
with open(local_filename, 'wb') as f, tqdm(
total=total_size, unit='B', unit_scale=True, unit_divisor=1024,
desc=local_filename, initial=0, ascii=True
) as pbar:
for chunk in r.iter_content(chunk_size=8192):
if chunk:
(chunk)
(len(chunk)) # 更新进度条
except as e:
print(f"下载失败: {e}")
except Exception as e:
print(f"发生其他错误: {e}")
print(f"文件 {local_filename} 下载完成！")

在上面的代码中，`tqdm`会根据`total_size`和每次`()`的字节数来显示进度。`unit_scale=True`和`unit_divisor=1024`等参数使得进度条能够以KB、MB、GB等更友好的单位显示。

实现断点续传（Resumable Download）

断点续传是分块下载的另一个强大应用。它允许在下载中断后，从上次停止的地方继续下载，而不是重新开始。这通过HTTP的`Range`请求头实现。

HTTP `Range`请求头

客户端可以通过在GET请求中包含`Range`头来指定只请求文件的一部分。例如：
`Range: bytes=0-499`：请求文件的前500个字节。
`Range: bytes=500-`：请求从第500个字节到文件末尾的所有数据。
`Range: bytes=-500`：请求文件的最后500个字节。

服务器在收到`Range`请求后，如果支持此功能，会返回一个`206 Partial Content`状态码，并在响应头中包含`Content-Range`来指示返回的数据范围。

断点续传的实现步骤

1. 检查本地文件： 在开始下载前，检查本地是否存在同名文件。如果存在，获取其当前大小。

2. 构建 `Range` 头： 如果本地文件大小大于0，则构建一个`Range`头，例如 `bytes=current_size-`，表示从`current_size`字节处开始下载。

3. 发送请求： 将包含`Range`头的请求发送给服务器。

4. 处理响应：

如果服务器返回`206 Partial Content`，说明续传成功。将新接收到的数据以追加模式写入本地文件。
如果服务器返回`200 OK`且没有`Content-Range`头，说明服务器不支持断点续传，或者请求的范围无效。此时应删除本地文件，从头开始下载。
如果返回其他错误码，进行相应处理。

断点续传代码示例

import requests
import os
from tqdm import tqdm
def download_file_resumable(url, local_filename, chunk_size=8192):
headers = {}
mode = 'wb' # 默认写入模式
# 检查本地文件是否存在及其大小
if (local_filename):
current_size = (local_filename)
headers['Range'] = f'bytes={current_size}-'
mode = 'ab' # 以追加模式打开文件
try:
with (url, headers=headers, stream=True) as r:
r.raise_for_status()
# 获取文件总大小和已下载大小
total_size = int(('content-length', 0))
if mode == 'ab': # 续传模式
# Content-Range 可能为 'bytes 2068-146515 / 146515'
content_range = ('content-range')
if content_range:
# 从Content-Range中解析出总大小，例如 'bytes 1000-1999/2000' -> 2000
total_size = int(('/')[-1])
downloaded_size = current_size # 已下载大小

# 如果服务器返回200而不是206，说明服务器不支持Range或Range无效，需重新下载
if r.status_code == 200 and current_size > 0:
print("服务器不支持断点续传，或Range请求无效，将重新下载。")
(local_filename)
download_file_resumable(url, local_filename, chunk_size) # 重新开始下载
return
else: # 全新下载模式
downloaded_size = 0
# 使用tqdm显示进度条
with open(local_filename, mode) as f, tqdm(
total=total_size, unit='B', unit_scale=True, unit_divisor=1024,
desc=local_filename, initial=downloaded_size, ascii=True
) as pbar:
for chunk in r.iter_content(chunk_size=chunk_size):
if chunk:
(chunk)
(len(chunk)) # 更新进度条
print(f"文件 {local_filename} 下载完成！")
except as e:
print(f"下载失败: {e}")
except Exception as e:
print(f"发生其他错误: {e}")
# 示例使用
download_url = "/" # 替换为实际的下载URL
output_filename = ('/')[-1]
download_file_resumable(download_url, output_filename)

在上述断点续传的示例中，我们首先检查本地文件，如果文件存在，则获取其大小并设置`Range`头。然后根据服务器返回的HTTP状态码（`206 Partial Content`表示续传成功，`200 OK`且本地文件存在则可能需要重新下载），决定是追加写入还是从头开始写入文件。`tqdm`的`initial`参数被设置为`downloaded_size`，确保进度条从正确的位置开始显示。

最佳实践与注意事项

资源关闭： 务必使用`with`语句来处理`requests`响应和文件对象，确保资源在操作完成后被正确关闭，即使发生异常。
错误处理： 除了网络异常（``），还要考虑文件I/O异常、权限问题等。
服务器兼容性： 并非所有服务器都支持`Range`头。在实现断点续传时，需要考虑服务器不支持的情况（通常表现为返回`200 OK`而不是`206 Partial Content`，且忽略`Range`头）。
`Content-Length`的可靠性： `Content-Length`头在某些情况下可能不存在或不准确（如动态内容），此时无法精确显示总进度。需要更鲁棒的逻辑来处理这种情况。
并发下载： 对于极致的下载速度需求，可以考虑使用多线程或异步IO技术同时下载文件的不同分块，最后再合并。但这会增加实现的复杂性。
安全性： 确保下载来源可靠，并对下载的文件进行校验，例如通过MD5、SHA256等哈希值验证。

在Python中，利用`requests`库进行高效的文件下载，尤其是对于大文件，分块传输是必不可少的技术。通过设置`stream=True`和使用`iter_content()`方法，我们可以轻松地实现流式下载，从而显著降低内存占用。在此基础上，结合HTTP的`Range`请求头，我们可以进一步实现强大的断点续传功能，极大地提升下载的鲁棒性和用户体验。掌握这些技术，将使你在处理文件下载任务时更加游刃有余，写出更加专业和健壮的Python应用程序。

2026-03-05

---

上一篇：Python 项目代码结构：构建可维护、可扩展和协作的基石

下一篇：Python字符串聚合深度解析：高效拼接、性能优化与实战技巧