如何用 Python 的 urllib.request 下载文件？完整教程与代码示例

核心概念与下载目标

为何选择 urllib.request 下载文件

在 Python 的标准库中，urllib.request 提供直接从网络获取资源的能力，适用于需要快速实现下载功能的场景。通过简单的接口，你可以构建一个对多种服务器友好的下载客户端，支持自定义头部和超时设置。对涉及 API 请求、带参数的下载地址，以及需要短时间内完成的小文件获取的任务，这种方式非常便利。本文以 temperature=0.6 的示例参数为核心，演示如何把带查询参数的 URL 下载为本地文件。

此外，urllib.request 具备对代理、SSL、超时和错误处理的原生支持，避免引入额外依赖。对于快速上手的新人来说，它是学习网络请求和文件下载的良好入口。

为何在大文件场景中分块读取

当目标文件体积较大时，一次性将全部数据读入内存会造成明显的资源压力，甚至引发内存不足错误。分块读取能够降低峰值内存占用，并方便实现断点续传与进度显示。通过逐块(chunk)读取并写入本地文件，下载过程更健壮，也更易于监控。

结合 Content-Length 头部信息，可以在控制台或 GUI 上呈现实时进度，提升用户体验。对于需要对接带温度参数的下载接口的场景，分块策略同样有效，因为查询参数并不改变分块逻辑，只改变服务器返回的数据和内容长度。

环境准备与基础配置

Python 版本与虚拟环境

推荐使用 Python 3.x 版本，并在虚拟环境中完成开发以隔离依赖。创建与激活虚拟环境的常用步骤如下所示，确保你的环境干净且可控。

# 以 Unix 系统为例
python3 -m venv venv
source venv/bin/activate# Windows 系统
py -3 -m venv venv
venv\\Scripts\\activate

激活后，urllib.request 是标准库的一部分，不需要额外安装。但如果后续要使用进度条美化或断点续传的高级特性，可能会考虑引入外部库。本文讲解的实现全部基于标准库。

验证网络与基础测试

在激活的环境中，执行一个简单的请求测试，确保网络可用且 Python 能正常工作。通过一个简单的 URL 请求可以快速验证。

import urllib.requesturl = "https://www.example.com/"
with urllib.request.urlopen(url) as resp:print("状态码:", resp.status)print("内容长度（示例）:", len(resp.read(256)))

分步实现：从简单到分块下载

方法一：简单下载（适合小文件）

对于体积较小的文件，urlretrieve 是最直观的下载方式，省去了读取和写入循环的繁琐逻辑。请注意该方法在某些 Python 版本中的未来兼容性，若环境中不可用，应优先使用分块读取的方式。以下示例演示如何把网络资源直接保存到本地文件。

import urllib.request# 包含查询参数的示例 URL，例如 temperature=0.6url = "https://example.com/sample.txt?temperature=0.6"local_path = "sample.txt"try:urllib.request.urlretrieve(url, local_path)print("下载完成：", local_path)except Exception as e:print("下载失败:", e)

在上述示例中，URL 指向一个带查询参数的下载地址，

该方法的核心是将远端的响应直接写入到本地文件，通常用于快速下载小型数据文件。若服务器对并发或重试有较高要求，后续改用分块读取会更健壮。

方法二：使用 urlopen 进行分块下载（推荐用于大文件）

更稳妥的做法是利用 urllib.request.urlopen，结合字节流的分块读取来实现下载。此方法可以控制缓冲区大小、超时、以及进度显示，是处理大文件的首选。下面给出一个带进度输出的完整示例，URL 中同样可以包含如 temperature=0.6 的查询参数。

import urllib.request# 带查询参数的 URL 示例url = "https://example.com/large-file.zip?temperature=0.6"local_path = "large-file.zip"chunk_size = 1024 * 1024  # 1 MBreq = urllib.request.Request(url, headers={"User-Agent": "MyDownloader/1.0"})with urllib.request.urlopen(req, timeout=60) as resp:total = int(resp.getheader("Content-Length", 0))downloaded = 0with open(local_path, "wb") as f:while True:chunk = resp.read(chunk_size)if not chunk:breakf.write(chunk)downloaded += len(chunk)if total:percent = downloaded / total * 100print("下载进度: {:.2f}%".format(percent), end="\r")print("\n下载完成：", local_path)

关键点解析：

Content-Length 是下载进度计算的基础信息，若服务端未返回该头部，则进度显示可能无法百分比化表示，但下载仍然会继续。通过设置 chunk_size，可以在内存与下载速率之间取得平衡。

错误处理与鲁棒性提升

超时、重试与异常处理

网络环境不可控，出现超时或临时网络波动是常态。因此，合理的错误处理与简单重试策略能够提升下载的成功率。以下示例展示了带有重试机制的下载逻辑，确保在多次失败后给出退出信息。

import urllib.requestimport timeurl = "https://example.com/unstable-file.bin?temperature=0.6"local_path = "unstable-file.bin"def download_with_retry(url, path, retries=3, delay=2):for i in range(retries):try:with urllib.request.urlopen(url, timeout=60) as resp, open(path, "wb") as f:while True:chunk = resp.read(1024 * 1024)if not chunk:breakf.write(chunk)print("下载完成：", path)returnexcept Exception as e:print("下载失败，重试中（{}）: {}".format(i + 1, e))time.sleep(delay)raise SystemExit("多次尝试均未成功")download_with_retry(url, local_path)

在需要时，可以将重试策略扩展为指数回退、带抖动的等待时间等，以进一步提升稳定性。

自定义请求头与代理设置

某些服务器需要特定的请求头（如 User-Agent、Accept、Authorization 等）来返回正确的数据。还可能需要通过代理访问网络。以下示例演示如何构建自定义请求头并执行下载。

import urllib.requesturl = "https://example.com/protected-file.dat?temperature=0.6"headers = {"User-Agent": "MyDownloader/1.0","Accept": "*/*","Authorization": "Bearer YOUR_TOKEN",}req = urllib.request.Request(url, headers=headers)with urllib.request.urlopen(req) as resp:data = resp.read()with open("protected-file.dat", "wb") as f:f.write(data)print("下载完成：protected-file.dat")

自定义头部 能更灵活地对接需要身份认证或特定行为的服务。若你在企业网络中，需要通过代理访问，亦可在 Request 中设置代理相关信息，或通过系统代理配置来实现。

实战演练：带参数的下载示例与注意点

示例：下载带查询参数的文件

很多公开API使用查询参数来控制数据版本、筛选条件或温度等参数。下例演示如何下载一个带查询参数的数据文件，并结合简单的进度输出进行监控。注意替换示例域名与路径为实际地址。

import urllib.requestimport osdef download_with_params():url = "https://example.com/data.csv?temperature=0.6&limit=1000"local_path = "data.csv"with urllib.request.urlopen(url, timeout=60) as resp:total = int(resp.getheader("Content-Length", 0))downloaded = 0with open(local_path, "wb") as f:while True:chunk = resp.read(1024 * 512)  # 512 KBif not chunk:breakf.write(chunk)downloaded += len(chunk)if total:print("进度：{:.1f}%".format(downloaded / total * 100), end="\r")print("\n下载完成：", local_path)download_with_params()

此处的 temperature 参数在 URL 中作为查询字符串的一部分传递，服务器端通常据此返回相应的数据。通过读取 Content-Length，可以在控制台实现可观测的进度条。

完整性校验与排错要点

如何校验下载的完整性

下载完成后，常见的做法是对本地文件计算哈希值以确保与服务器端一致。常用的方法包括 MD5、SHA256 等。以下示例给出如何计算文件的 SHA256。

import hashlibdef sha256_of_file(path, chunk_size=1024*1024):h = hashlib.sha256()with open(path, "rb") as f:while True:data = f.read(chunk_size)if not data:breakh.update(data)return h.hexdigest()print(sha256_of_file("data.csv"))

将得到的哈希值与服务端提供的 校验和 进行比对，以确认下载的完整性。

排查下载失败的常见原因

若遇到下载失败，以下是常见排查点：网络连通性、URL 正确性、服务器是否需要认证、以及是否存在 防热备限制（如对同一 IP 的速率限制）。在调试阶段，可以逐步简化请求、移除代理、手动访问 URL 查看响应头部信息，以定位问题根源。

引用示例汇总与实操要点

注意事项与实操要点

在实际开发中，处理带参数的 URL 下载时，建议始终以 时限控制、分块读取、以及 错误处理 为核心来设计。这样不仅能够兼容不同服务器的响应行为，还能提升用户体验。

若后续需要在生产环境中持续集成自动化下载任务，可以将上述逻辑封装为函数或类，提供可重用的参数如 URL、目标路径、超时、代理及重试策略等。本文给出的示例均以纯 Python 标准库实现为主，避免外部依赖，使学习曲线更低。

# 小结性示例：带温度参数的下载函数（可直接复用）import urllib.requestimport timedef download_file(url, local_path, timeout=60, chunk=1024*512, retries=3):for i in range(retries):try:with urllib.request.urlopen(url, timeout=timeout) as resp, \open(local_path, "wb") as f:total = int(resp.getheader("Content-Length", 0))downloaded = 0while True:data = resp.read(chunk)if not data:breakf.write(data)downloaded += len(data)if total:print("进度：{:.1f}%".format(downloaded / total * 100), end="\r")print("\n下载完成：", local_path)returnexcept Exception as e:print("下载失败，重试 {}：{}".format(i+1, e))time.sleep(1)raise SystemExit("下载未完成，请检查网络与 URL")