简介这是一份围绕Python requests模块整理的源码与文档资料包面向希望告别urllib2繁琐调用的Python开发者。requests凭借简洁API成为主流的HTTP客户端库资源通过实际源码展示请求发送、响应处理、会话维持等核心用法便于快速上手与研读。压缩包共121个文件以76个py源码、20个rst说明文档和5个html页面为主辅以配置、样式与许可证文件整体仅643KB轻量清晰目录结构兼顾功能模块与文档说明适合按需查阅。内容既覆盖requests与urllib2的对比也保留了项目构建所需的配置与主题文件适合初学者对照学习也可供开发者提取HTTP请求工具函数复用。截至目前已有7017人学习下载是一份值得收藏的便携式参考文献。1. 用 requests 模块下载文件为什么这个标题值得你花十分钟用 requests 模块下载文件听起来就是把一次 GET 请求的响应写进本地文件几句话就能写完。但真正跑过生产下载任务的人都知道这里的坑远比想象中多文件一大内存先爆网络一抖脚本原地挂死服务器一个 403你连问题出在哪都找不到。这篇文章面向正在写下载脚本的 Python 开发者从最小可用的下载代码讲起逐步补齐超时、重试、断点续传和完整性校验最后给一个带进度显示、支持多文件并发的下载器模板可以直接抄进自己的工具库。全程不绕弯子每一段都能对应到一个实际会踩的问题。2. 先跑通最小下载response.content、stream 与 iter_content 的取舍requests 的下载本质上是把 HTTP 响应体保存成本地文件。同样是发一次 GET读取响应体的姿势有三种直接取 response.content、streamTrue 配合 iter_content 流式遍历、走 response.raw 底层流。选错姿势不是功能跑不通而是内存模型和稳定性完全不同。先看结论读取方式内存模型适用场景主要风险response.content一次性全量读入内存100MB 以内的小文件大文件或高并发下 OOMiter_content按块读取读完即释放任意大小日常最推荐chunk_size 过大仍会抬高内存峰值response.raw copyfileobj流式拷贝少一层封装追求极致吞吐不会自动解压需自行处理编码三种方式我都在项目里实际用过下面逐个说清楚写法、参数和边界。2.1 小文件场景response.content 一把梭的写法与内存边界最简单也最省事的方式是直接取 content几 MB 到几十 MB 的文件用它最合适import requests url https://example.com/files/report.pdf resp requests.get(url, timeout(5, 15)) resp.raise_for_status() # 状态码不是 2xx 时直接抛异常 with open(report.pdf, wb) as f: f.write(resp.content) # 一次性读取整个响应体这段代码的逻辑很直白先发 GET 请求raise_for_status() 确保 4xx/5xx 错误不会混进下载流程再把 resp.content 整个写进文件。resp.content 的背后是 requests 把响应体完整读进内存、以 bytes 对象返回所以内存占用和文件大小是 1:1 的关系。参数上只有两个地方需要关心。timeout(5, 15) 是二元组第一个 5 秒是连接超时第二个 15 秒是读超时具体语义第 3 章展开。open 的 wb 是二进制写模式bytes 数据必须用二进制模式落盘写成 w 会在遇到非 ASCII 字节时抛 UnicodeEncodeError。content 的边界在哪我的经验警戒线是 100MB。单文件 100MB 以内内存占用可以接受超过这个量级或者脚本要并发下多个文件就必须换流式方案。某数据同步脚本曾用 content 并发下载 20 个 80MB 的 CSV八个线程同时跑内存冲到 1.6GB 被系统杀掉。记住一个公式并发数 × 单文件大小 ≈ 脚本峰值内存这个值要控制在机器可用内存的一半以下。2.2 大文件场景streamTrue 配合 iter_content 分块落盘大文件下载的正确姿势是流式处理。streamTrue 让 requests 只建立连接、先不读响应体之后用 iter_content 一块一块取数据import requests url https://example.com/files/big_model.bin resp requests.get(url, streamTrue, timeout(5, 30)) resp.raise_for_status() with open(big_model.bin, wb) as f: for chunk in resp.iter_content(chunk_size8192): if chunk: # 过滤 keep-alive 产生的空块 f.write(chunk)逻辑说明streamTrue 的本质是延迟读取响应对象返回时只有响应头body 还在网络缓冲区里。iter_content(chunk_size8192) 每次最多从底层套接字读 8KB写入文件后立即释放这块内存所以整个下载过程内存占用是稳定的和文件总大小无关。chunk_size 不是一个越大越好的参数。8KB 到 64KB 是常见区间系统调用次数和内存占用比较均衡设成 1KB 会因读写系统调用过频拖慢速度设成 1MB 以上并发场景下内存峰值会明显抬升。if chunk 的判断背后也有实际原因TCP keep-alive 或代理转发场景下可能返回空块虽然写空块不报错但过滤掉能少做一次无意义的写操作。这里提醒两个容易混的点。第一iter_content 是按字节块迭代适合二进制文件如果误用 iter_lines那是按行迭代只适合日志这类文本流遇到二进制数据直接出乱码。第二streamTrue 的响应在读完 body 之前一直占用着连接不要把它丢进大并发循环里不管后面第 5 章的并发模板会给出正确写法。相比 content流式方案在下载中断时能保留已写入的部分这也是断点续传能成立的前提。2.3 用 response.raw 走最底层拷贝省掉一层封装第三种姿势适合追求极致吞吐的场景用 shutil 的 copyfileobj 直接从 raw 流拷到文件对象import requests import shutil resp requests.get(url, streamTrue, timeout(5, 30)) resp.raise_for_status() with open(big_model.bin, wb) as f: shutil.copyfileobj(resp.raw, f, length64 * 1024)逻辑说明resp.raw 是 urllib3 的 HTTPResponse 对象比 requests 封装的 iter_content 更接近套接字少一层生成器开销。copyfileobj 会反复从 src 读 length 字节写入 dst 直到 EOF等价于替你写好了循环。但这个方案有个大坑走 raw 时requests 的自动解压默认不生效。如果服务器返回 Content-Encoding: gzip你存下来的是压缩后的字节流文件打开就是乱的。要安全使用 raw要么在请求头里加 Accept-Encoding: identity 让服务器别压缩要么自己读 Content-Encoding 后手动解压。相比之下 iter_content 会自动处理解压这也是我日常更推荐 iter_content 的原因少一个隐藏条件。提示无论用 iter_content 还是 rawstreamTrue 的响应都必须把 body 读完或显式调用 resp.close()否则连接不会归还给连接池。单次下载看不出问题高并发下连接会被逐渐耗尽表现就是越下越慢最后卡死。3. 下载的稳定性参数超时、重试、请求头与 Range 断点下载任务和普通接口调用的最大区别是运行时长。一次接口调用撑死几秒一次下载可能持续几分钟甚至几小时因此失败模式完全不同。这一章把四个决定下载稳定性的参数逐一说透。3.1 timeout 拆开设connect 超时和 read 超时是两回事很多教程只教你写 timeout5这个写法在下载场景里不够用甚至会造成误导。requests 的 timeout 传单个数字时连接超时和读超时共用这个值传二元组时可以分开控制。下载大文件时最典型的翻车是有人把读超时设成 30 秒然后拿着 1GB 的文件抱怨脚本总是超时——其实读超时根本不是总时长限制它管的是两个数据块之间的最大空闲间隔。import requests url https://example.com/files/big_file.iso # 3.05 秒内建立 TCP 连接60 秒内必须收到下一个数据块 resp requests.get(url, streamTrue, timeout(3.05, 60))逻辑说明第一个值 3.05 是 connect 超时从发起请求到 TCP 连接建立的等待上限第二个值 60 是 read 超时相邻两次读到数据之间的最大空闲间隔。下载 2GB 的文件只要数据在持续到达哪怕下了一小时也不会触发读超时如果服务器 accept 连接后一直不发数据或者下载中途网络黑洞读超时才是让你退出的唯一机制。参数策略上我的习惯是连接超时设短一点3 到 5 秒就够连不上就是连不上等再久也没意义读超时设 30 到 60 秒但要大于服务器两次发包之间可能出现的最大间隔有些动态生成文件的服务器首字节要等十几秒设太短会把正常下载误杀。timeout 不传等于 None也就是永久等待这是下载挂死的第一大原因下面两个参数也一样重要。3.2 用 Session urllib3 Retry 把重试写成默认行为网络抖动是下载任务的家常便饭与其在业务代码里到处写 try-except 重试不如把重试配置在传输层让 Session 默认就具备抗抖动能力from requests import Session from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry retry Retry( total3, connect3, read3, backoff_factor0.5, status_forcelist[500, 502, 503, 504], allowed_methods[GET], ) session Session() adapter HTTPAdapter(max_retriesretry) session.mount(https://, adapter) session.mount(http://, adapter)逻辑说明Retry 是 urllib3 的配置对象HTTPAdapter 把它桥接到 requests 的 Session 上。total3 表示最多重试 3 次connect3 和 read3 分别限制连接失败和读失败的重试次数status_forcelist 里的 500、502、503、504 也会触发重试allowed_methods[GET] 限定只有 GET 会重试避免 POST 等非幂等请求被重复提交。参数说明backoff_factor0.5 控制重试间隔按 0.5 × 2^n 计算第一次约 0.5 秒、第二次 1 秒、第三次 2 秒指数退避能明显降低对服务器的瞬时压力。如果不设 backoff_factor默认是 0失败后立即重试这等于没有退避生产环境对服务器很不友好。注意 Retry 只覆盖连接错误和 status_forcelist 里的状态码不覆盖下载到一半连接断开那种场景要靠 Range 续传补上。Session 对象还顺带解决了连接池复用和 Cookie 维持的问题同一个 Session 发多次请求会自动复用底层连接。3.3 请求头UA、Accept-Encoding 与 Content-Disposition 文件名下载请求的请求头比普通接口更讲究三个字段需要特别关注headers { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64), Accept-Encoding: identity, # 要求服务器返回原始字节 } resp requests.get(url, headersheaders, streamTrue, timeout(5, 30)) print(状态码:, resp.status_code) print(文件大小:, resp.headers.get(Content-Length)) print(是否支持断点:, resp.headers.get(Accept-Ranges)) print(服务端文件名:, resp.headers.get(Content-Disposition))逻辑说明User-Agent 的作用是让服务器不要一眼认出你是脚本。requests 默认的 UA 是 python-requests/2.x.x很多下载服务器、图床和文件分发服务见到这个 UA 直接 403。Accept-Encoding: identity 是更隐蔽但更关键的一个头它要求服务器不要压缩响应体这样 Content-Length 和你实际写入的字节数严格一致进度计算和 MD5 校验才做得准。文件名的处理是下载场景特有的问题。服务器返回的文件名通常在 Content-Disposition 头里旧式写法是 filenamereport.pdf新版标准是 filename*UTF-8%E4%B8%AD.pdfRFC 5987 编码只取旧字段在中文文件名场景下必然乱码。解析时要优先取 filename*import re from urllib.parse import unquote def extract_filename(disposition, url): if disposition: m re.search(rfilename\*?(?:UTF-8)?\?([^\;]), disposition, re.I) if m: return unquote(m.group(1)) # 解码 %XX return unquote(url.split(/)[-1]) # 取不到就退回 URL 最后一段逻辑说明正则里先尝试匹配 filename* 的格式捕获后用 unquote 把 %XX 还原成中文字符匹配不到就退回 filename 字段整个头都不存在就取 URL 最后一段。保存路径前建议再用 os.path.basename 过滤一次防止服务器把文件名构造得像 ../../etc/passwd 造成路径穿越。3.4 Range 断点续传206 与 200 的判断是全部逻辑核心断点续传的价值在于避免前功尽弃实现依赖 HTTP 的 Range 语义。核心逻辑是本地已有文件就带上 Range 头然后根据响应状态码决定继续追加还是从头重下import os import requests def download_resume(url, filepath): headers {User-Agent: Mozilla/5.0} resume_pos os.path.getsize(filepath) if os.path.exists(filepath) else 0 if resume_pos: headers[Range] fbytes{resume_pos}- resp requests.get(url, headersheaders, streamTrue, timeout(5, 30)) if resp.status_code 206: # Partial Content服务器接受了 Range mode ab else: # 服务器忽略 Range 返回 200只能覆盖重下 mode wb resume_pos 0 with open(filepath, mode) as f: for chunk in resp.iter_content(chunk_size65536): if chunk: f.write(chunk) return filepath逻辑说明resume_pos 来自本地已有文件的大小通过 Range 头告诉服务器从哪个字节开始。status_code 是 206 还是 200 是整个函数的判断核心服务器支持 Range 就返回 206 并带上 Content-Range此时用 ab 追加写不支持 Range 就返回 200 全量内容此时必须用 wb 覆盖从头写否则新内容被拼在旧文件尾巴上得到一个损坏文件。续传完成后的校验容易漏206 响应的 Content-Length 是剩余部分的长度不是文件总长度要用已写入字节数加上它去和预期总大小比对。另外续传只是手段最终的文件完整性仍然要靠 MD5 验证兜底。如果服务器支持 Range 但文件源在两次请求之间变了源文件被重新上传续传会得到一个两头不匹配的坏文件MD5 是唯一能发现这个问题的环节。4. 下载避坑指南5 个翻车现场与排查路径第 2、3 章是正确做法这一章是正确做法的反面清单。以下五个坑都在真实下载任务里反复出现过每一条按现象、原因、解决三个步骤展开建议对照自己的代码排查。4.1 下载到一半内存飙升脚本被 OOM 干掉现象下载一个几百 MB 的模型文件脚本进程内存从 100MB 一路涨到 1.5GB最后被系统直接 kill日志里什么都没留下。原因最普遍的是没用 streamTruerequests.get() 默认在响应到达时把整个 body 读进内存。另一个隐蔽的情况是加了 streamTrue但后面手滑用了 resp.content这个属性同样会触发全量读取stream 白加了。解决大文件一律走 streamTrue iter_content 分块落盘直接用第 2.2 节的模板。在循环里加一个每写入 1000 块打印一次已写入字节数的统计点内存异常时能立刻定位是读取姿势的问题还是 chunk_size 设得过大。chunk_size 超过 256KB 且并发数大于 4 时内存峰值会非常明显。4.2 下载完的文件大小对不上MD5 校验失败现象文件正常落盘但一解压就报错或者和发布方给的 MD5 对不上大小差了几百 KB。原因三个来源最常见。第一URL 不存在但服务器返回了 200body 是错误页或首页 HTML这种最坑因为代码不会报错第二服务器开了 gzipContent-Length 是压缩后的大小而 requests 自动解压后存进文件的是原始数据两者天然对不上第三下载中途断连但脚本没感知把半截文件当完整文件收尾了。解决下载前置两道校验。第一resp.raise_for_status() 确保状态码是 2xx再确认 Content-Type 是预期类型第二请求头设 Accept-Encoding: identity让 Content-Length 与写入字节严格一致。下载完成后用 os.path.getsize 和 Content-Length 比对再跑一次 MD5对不上就删除重下。无人值守脚本里这一条是基本素养。4.3 下载卡住不动既不报错也不结束现象脚本停在原地进度百分比不动CtrlC 之后 traceback 停在 iter_content 的读取那一行看起来什么都没做。原因九成是 timeout 没设全。要么没写 timeout要么只写了一个数字。连接建立后服务器一直不发数据TCP 层面没有任何错误信号读超时又是 None代码就无限等下去。某些 CDN 边缘节点回源慢时会出现这种连接在了但数据不来的情况。解决timeout 设成 (connect, read) 二元组read 给 60 秒。再套一层总时长护栏记录开始时间在循环里判断 elapsed超过上限主动抛异常退出。读超时是数据块之间空闲时间的上限不是总时长这个语义在第 3.1 节已经强调过这里是它最典型的应用场景。4.4 服务器返回 403浏览器却能正常下载现象同一个 URL浏览器右键另存为没问题脚本一跑就是 403 Forbidden响应体是一个不说明任何问题的错误页。原因服务器在检测客户端。requests 默认 UA 是 python-requests/2.x.x特征太明显很多下载服务器直接拒绝。另一种情况是校验 Referer要求请求必须携带特定页面跳转的来源裸请求没有这个头。解决先把 User-Agent 换成浏览器的完整 UA一半以上的 403 到此解决。还不行就打开浏览器开发者工具的 Network 面板重新触发一次下载把那次请求的 User-Agent、Referer、Accept、Cookie 原样复制进脚本。涉及登录态的资源用 requests.Session() 先走登录流程让 Session 把 Cookie 带上再发起下载。4.5 断点续传续出来一个坏文件现象下载中断后重跑脚本任务显示完成但文件校验失败打开一看开头是乱码或者文件大小比预期大了一截。原因文件打开模式写错。服务器接受 Range 返回 206应该用 ab 追加服务器不支持 Range 返回 200 全量内容必须用 wb 覆盖。很多人只写了 ab在服务器不支持 Range 的场景下新内容被追加到旧文件尾部中间还缺一段文件直接废掉。解决根据 status_code 决定模式206 追加、200 覆盖代码见第 3.4 节。续传完成后用已写入字节数加 206 响应的 Content-Length 去和预期总大小比对最后跑一次 MD5。续传逻辑越复杂越需要一个最终校验兜底这条不要省。提示文件名乱码不在上面五条里但遇到概率很高。解析优先级是 filename*UTF-8 优先退回 filename再退回 URL 末段拿到后先 unquote 解码、再 os.path.basename 过滤代码模板在第 3.3 节。5. 把下载器做成能用的工具进度显示与多文件并行前面章节解决能不能下完这一章给一个抄完就能跑的下载器模板把进度显示和多文件并发合在一起。5.1 带进度显示的下载函数import sys import requests def download_one(session, url, filepath): resp session.get(url, streamTrue, timeout(5, 60), headers{ User-Agent: Mozilla/5.0, Accept-Encoding: identity, }) resp.raise_for_status() total int(resp.headers.get(Content-Length, 0)) done 0 with open(filepath, wb) as f: for chunk in resp.iter_content(chunk_size65536): if not chunk: continue f.write(chunk) done len(chunk) if total: sys.stdout.write(f\r{filepath}: {done / total * 100:.1f}%) sys.stdout.flush() print(f\n{filepath} 完成共 {done} 字节)参数说明session 由外部传入多文件并发时复用连接池Content-Length 为 0 时跳过百分比只显示已下载字节数\r 让进度在同一行刷新不刷屏。total 拿不到时部分服务器不返回 Content-Length进度条会自动降级成字节计数不影响功能。5.2 并发入口ThreadPoolExecutorfrom concurrent.futures import ThreadPoolExecutor, as_completed from requests import Session urls { https://example.com/files/a.zip: a.zip, https://example.com/files/b.zip: b.zip, https://example.com/files/c.zip: c.zip, } session Session() with ThreadPoolExecutor(max_workers4) as pool: futures {pool.submit(download_one, session, u, p): u for u, p in urls.items()} for fut in as_completed(futures): try: fut.result() except Exception as e: print(f{futures[fut]} 失败: {e})参数说明max_workers 建议 4 到 6下载是 I/O 密集操作线程完全够用不需要上多进程worker 开太多会被服务器限速甚至封禁。Session 是线程安全的可以放心在多个线程间共享它会自动复用底层 TCP 连接避免每个文件都重新握手。这套模板是我现在写下载脚本的标准开头加校验、加断点续传、加限速都在这个骨架上扩展。我最早写下载脚本时内存爆过、续传续出过坏文件、403 卡了半天才反应过来是 UA 的问题后来把超时、重试、校验这三件事固化进模板才踏实下来。这个方向值不值得投入我的判断很简单只要你的下载脚本要离开本地手跑、进入服务器或定时任务第 3 章和第 4 章讲的每一件事都值得现在就补上。希望帮到你。本文还有配套的精品资源点击获取
简介这是一份围绕Python requests模块整理的源码与文档资料包面向希望告别urllib2繁琐调用的Python开发者。requests凭借简洁API成为主流的HTTP客户端库资源通过实际源码展示请求发送、响应处理、会话维持等核心用法便于快速上手与研读。压缩包共121个文件以76个py源码、20个rst说明文档和5个html页面为主辅以配置、样式与许可证文件整体仅643KB轻量清晰目录结构兼顾功能模块与文档说明适合按需查阅。内容既覆盖requests与urllib2的对比也保留了项目构建所需的配置与主题文件适合初学者对照学习也可供开发者提取HTTP请求工具函数复用。截至目前已有7017人学习下载是一份值得收藏的便携式参考文献。1. 用 requests 模块下载文件为什么这个标题值得你花十分钟用 requests 模块下载文件听起来就是把一次 GET 请求的响应写进本地文件几句话就能写完。但真正跑过生产下载任务的人都知道这里的坑远比想象中多文件一大内存先爆网络一抖脚本原地挂死服务器一个 403你连问题出在哪都找不到。这篇文章面向正在写下载脚本的 Python 开发者从最小可用的下载代码讲起逐步补齐超时、重试、断点续传和完整性校验最后给一个带进度显示、支持多文件并发的下载器模板可以直接抄进自己的工具库。全程不绕弯子每一段都能对应到一个实际会踩的问题。2. 先跑通最小下载response.content、stream 与 iter_content 的取舍requests 的下载本质上是把 HTTP 响应体保存成本地文件。同样是发一次 GET读取响应体的姿势有三种直接取 response.content、streamTrue 配合 iter_content 流式遍历、走 response.raw 底层流。选错姿势不是功能跑不通而是内存模型和稳定性完全不同。先看结论读取方式内存模型适用场景主要风险response.content一次性全量读入内存100MB 以内的小文件大文件或高并发下 OOMiter_content按块读取读完即释放任意大小日常最推荐chunk_size 过大仍会抬高内存峰值response.raw copyfileobj流式拷贝少一层封装追求极致吞吐不会自动解压需自行处理编码三种方式我都在项目里实际用过下面逐个说清楚写法、参数和边界。2.1 小文件场景response.content 一把梭的写法与内存边界最简单也最省事的方式是直接取 content几 MB 到几十 MB 的文件用它最合适import requests url https://example.com/files/report.pdf resp requests.get(url, timeout(5, 15)) resp.raise_for_status() # 状态码不是 2xx 时直接抛异常 with open(report.pdf, wb) as f: f.write(resp.content) # 一次性读取整个响应体这段代码的逻辑很直白先发 GET 请求raise_for_status() 确保 4xx/5xx 错误不会混进下载流程再把 resp.content 整个写进文件。resp.content 的背后是 requests 把响应体完整读进内存、以 bytes 对象返回所以内存占用和文件大小是 1:1 的关系。参数上只有两个地方需要关心。timeout(5, 15) 是二元组第一个 5 秒是连接超时第二个 15 秒是读超时具体语义第 3 章展开。open 的 wb 是二进制写模式bytes 数据必须用二进制模式落盘写成 w 会在遇到非 ASCII 字节时抛 UnicodeEncodeError。content 的边界在哪我的经验警戒线是 100MB。单文件 100MB 以内内存占用可以接受超过这个量级或者脚本要并发下多个文件就必须换流式方案。某数据同步脚本曾用 content 并发下载 20 个 80MB 的 CSV八个线程同时跑内存冲到 1.6GB 被系统杀掉。记住一个公式并发数 × 单文件大小 ≈ 脚本峰值内存这个值要控制在机器可用内存的一半以下。2.2 大文件场景streamTrue 配合 iter_content 分块落盘大文件下载的正确姿势是流式处理。streamTrue 让 requests 只建立连接、先不读响应体之后用 iter_content 一块一块取数据import requests url https://example.com/files/big_model.bin resp requests.get(url, streamTrue, timeout(5, 30)) resp.raise_for_status() with open(big_model.bin, wb) as f: for chunk in resp.iter_content(chunk_size8192): if chunk: # 过滤 keep-alive 产生的空块 f.write(chunk)逻辑说明streamTrue 的本质是延迟读取响应对象返回时只有响应头body 还在网络缓冲区里。iter_content(chunk_size8192) 每次最多从底层套接字读 8KB写入文件后立即释放这块内存所以整个下载过程内存占用是稳定的和文件总大小无关。chunk_size 不是一个越大越好的参数。8KB 到 64KB 是常见区间系统调用次数和内存占用比较均衡设成 1KB 会因读写系统调用过频拖慢速度设成 1MB 以上并发场景下内存峰值会明显抬升。if chunk 的判断背后也有实际原因TCP keep-alive 或代理转发场景下可能返回空块虽然写空块不报错但过滤掉能少做一次无意义的写操作。这里提醒两个容易混的点。第一iter_content 是按字节块迭代适合二进制文件如果误用 iter_lines那是按行迭代只适合日志这类文本流遇到二进制数据直接出乱码。第二streamTrue 的响应在读完 body 之前一直占用着连接不要把它丢进大并发循环里不管后面第 5 章的并发模板会给出正确写法。相比 content流式方案在下载中断时能保留已写入的部分这也是断点续传能成立的前提。2.3 用 response.raw 走最底层拷贝省掉一层封装第三种姿势适合追求极致吞吐的场景用 shutil 的 copyfileobj 直接从 raw 流拷到文件对象import requests import shutil resp requests.get(url, streamTrue, timeout(5, 30)) resp.raise_for_status() with open(big_model.bin, wb) as f: shutil.copyfileobj(resp.raw, f, length64 * 1024)逻辑说明resp.raw 是 urllib3 的 HTTPResponse 对象比 requests 封装的 iter_content 更接近套接字少一层生成器开销。copyfileobj 会反复从 src 读 length 字节写入 dst 直到 EOF等价于替你写好了循环。但这个方案有个大坑走 raw 时requests 的自动解压默认不生效。如果服务器返回 Content-Encoding: gzip你存下来的是压缩后的字节流文件打开就是乱的。要安全使用 raw要么在请求头里加 Accept-Encoding: identity 让服务器别压缩要么自己读 Content-Encoding 后手动解压。相比之下 iter_content 会自动处理解压这也是我日常更推荐 iter_content 的原因少一个隐藏条件。提示无论用 iter_content 还是 rawstreamTrue 的响应都必须把 body 读完或显式调用 resp.close()否则连接不会归还给连接池。单次下载看不出问题高并发下连接会被逐渐耗尽表现就是越下越慢最后卡死。3. 下载的稳定性参数超时、重试、请求头与 Range 断点下载任务和普通接口调用的最大区别是运行时长。一次接口调用撑死几秒一次下载可能持续几分钟甚至几小时因此失败模式完全不同。这一章把四个决定下载稳定性的参数逐一说透。3.1 timeout 拆开设connect 超时和 read 超时是两回事很多教程只教你写 timeout5这个写法在下载场景里不够用甚至会造成误导。requests 的 timeout 传单个数字时连接超时和读超时共用这个值传二元组时可以分开控制。下载大文件时最典型的翻车是有人把读超时设成 30 秒然后拿着 1GB 的文件抱怨脚本总是超时——其实读超时根本不是总时长限制它管的是两个数据块之间的最大空闲间隔。import requests url https://example.com/files/big_file.iso # 3.05 秒内建立 TCP 连接60 秒内必须收到下一个数据块 resp requests.get(url, streamTrue, timeout(3.05, 60))逻辑说明第一个值 3.05 是 connect 超时从发起请求到 TCP 连接建立的等待上限第二个值 60 是 read 超时相邻两次读到数据之间的最大空闲间隔。下载 2GB 的文件只要数据在持续到达哪怕下了一小时也不会触发读超时如果服务器 accept 连接后一直不发数据或者下载中途网络黑洞读超时才是让你退出的唯一机制。参数策略上我的习惯是连接超时设短一点3 到 5 秒就够连不上就是连不上等再久也没意义读超时设 30 到 60 秒但要大于服务器两次发包之间可能出现的最大间隔有些动态生成文件的服务器首字节要等十几秒设太短会把正常下载误杀。timeout 不传等于 None也就是永久等待这是下载挂死的第一大原因下面两个参数也一样重要。3.2 用 Session urllib3 Retry 把重试写成默认行为网络抖动是下载任务的家常便饭与其在业务代码里到处写 try-except 重试不如把重试配置在传输层让 Session 默认就具备抗抖动能力from requests import Session from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry retry Retry( total3, connect3, read3, backoff_factor0.5, status_forcelist[500, 502, 503, 504], allowed_methods[GET], ) session Session() adapter HTTPAdapter(max_retriesretry) session.mount(https://, adapter) session.mount(http://, adapter)逻辑说明Retry 是 urllib3 的配置对象HTTPAdapter 把它桥接到 requests 的 Session 上。total3 表示最多重试 3 次connect3 和 read3 分别限制连接失败和读失败的重试次数status_forcelist 里的 500、502、503、504 也会触发重试allowed_methods[GET] 限定只有 GET 会重试避免 POST 等非幂等请求被重复提交。参数说明backoff_factor0.5 控制重试间隔按 0.5 × 2^n 计算第一次约 0.5 秒、第二次 1 秒、第三次 2 秒指数退避能明显降低对服务器的瞬时压力。如果不设 backoff_factor默认是 0失败后立即重试这等于没有退避生产环境对服务器很不友好。注意 Retry 只覆盖连接错误和 status_forcelist 里的状态码不覆盖下载到一半连接断开那种场景要靠 Range 续传补上。Session 对象还顺带解决了连接池复用和 Cookie 维持的问题同一个 Session 发多次请求会自动复用底层连接。3.3 请求头UA、Accept-Encoding 与 Content-Disposition 文件名下载请求的请求头比普通接口更讲究三个字段需要特别关注headers { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64), Accept-Encoding: identity, # 要求服务器返回原始字节 } resp requests.get(url, headersheaders, streamTrue, timeout(5, 30)) print(状态码:, resp.status_code) print(文件大小:, resp.headers.get(Content-Length)) print(是否支持断点:, resp.headers.get(Accept-Ranges)) print(服务端文件名:, resp.headers.get(Content-Disposition))逻辑说明User-Agent 的作用是让服务器不要一眼认出你是脚本。requests 默认的 UA 是 python-requests/2.x.x很多下载服务器、图床和文件分发服务见到这个 UA 直接 403。Accept-Encoding: identity 是更隐蔽但更关键的一个头它要求服务器不要压缩响应体这样 Content-Length 和你实际写入的字节数严格一致进度计算和 MD5 校验才做得准。文件名的处理是下载场景特有的问题。服务器返回的文件名通常在 Content-Disposition 头里旧式写法是 filenamereport.pdf新版标准是 filename*UTF-8%E4%B8%AD.pdfRFC 5987 编码只取旧字段在中文文件名场景下必然乱码。解析时要优先取 filename*import re from urllib.parse import unquote def extract_filename(disposition, url): if disposition: m re.search(rfilename\*?(?:UTF-8)?\?([^\;]), disposition, re.I) if m: return unquote(m.group(1)) # 解码 %XX return unquote(url.split(/)[-1]) # 取不到就退回 URL 最后一段逻辑说明正则里先尝试匹配 filename* 的格式捕获后用 unquote 把 %XX 还原成中文字符匹配不到就退回 filename 字段整个头都不存在就取 URL 最后一段。保存路径前建议再用 os.path.basename 过滤一次防止服务器把文件名构造得像 ../../etc/passwd 造成路径穿越。3.4 Range 断点续传206 与 200 的判断是全部逻辑核心断点续传的价值在于避免前功尽弃实现依赖 HTTP 的 Range 语义。核心逻辑是本地已有文件就带上 Range 头然后根据响应状态码决定继续追加还是从头重下import os import requests def download_resume(url, filepath): headers {User-Agent: Mozilla/5.0} resume_pos os.path.getsize(filepath) if os.path.exists(filepath) else 0 if resume_pos: headers[Range] fbytes{resume_pos}- resp requests.get(url, headersheaders, streamTrue, timeout(5, 30)) if resp.status_code 206: # Partial Content服务器接受了 Range mode ab else: # 服务器忽略 Range 返回 200只能覆盖重下 mode wb resume_pos 0 with open(filepath, mode) as f: for chunk in resp.iter_content(chunk_size65536): if chunk: f.write(chunk) return filepath逻辑说明resume_pos 来自本地已有文件的大小通过 Range 头告诉服务器从哪个字节开始。status_code 是 206 还是 200 是整个函数的判断核心服务器支持 Range 就返回 206 并带上 Content-Range此时用 ab 追加写不支持 Range 就返回 200 全量内容此时必须用 wb 覆盖从头写否则新内容被拼在旧文件尾巴上得到一个损坏文件。续传完成后的校验容易漏206 响应的 Content-Length 是剩余部分的长度不是文件总长度要用已写入字节数加上它去和预期总大小比对。另外续传只是手段最终的文件完整性仍然要靠 MD5 验证兜底。如果服务器支持 Range 但文件源在两次请求之间变了源文件被重新上传续传会得到一个两头不匹配的坏文件MD5 是唯一能发现这个问题的环节。4. 下载避坑指南5 个翻车现场与排查路径第 2、3 章是正确做法这一章是正确做法的反面清单。以下五个坑都在真实下载任务里反复出现过每一条按现象、原因、解决三个步骤展开建议对照自己的代码排查。4.1 下载到一半内存飙升脚本被 OOM 干掉现象下载一个几百 MB 的模型文件脚本进程内存从 100MB 一路涨到 1.5GB最后被系统直接 kill日志里什么都没留下。原因最普遍的是没用 streamTruerequests.get() 默认在响应到达时把整个 body 读进内存。另一个隐蔽的情况是加了 streamTrue但后面手滑用了 resp.content这个属性同样会触发全量读取stream 白加了。解决大文件一律走 streamTrue iter_content 分块落盘直接用第 2.2 节的模板。在循环里加一个每写入 1000 块打印一次已写入字节数的统计点内存异常时能立刻定位是读取姿势的问题还是 chunk_size 设得过大。chunk_size 超过 256KB 且并发数大于 4 时内存峰值会非常明显。4.2 下载完的文件大小对不上MD5 校验失败现象文件正常落盘但一解压就报错或者和发布方给的 MD5 对不上大小差了几百 KB。原因三个来源最常见。第一URL 不存在但服务器返回了 200body 是错误页或首页 HTML这种最坑因为代码不会报错第二服务器开了 gzipContent-Length 是压缩后的大小而 requests 自动解压后存进文件的是原始数据两者天然对不上第三下载中途断连但脚本没感知把半截文件当完整文件收尾了。解决下载前置两道校验。第一resp.raise_for_status() 确保状态码是 2xx再确认 Content-Type 是预期类型第二请求头设 Accept-Encoding: identity让 Content-Length 与写入字节严格一致。下载完成后用 os.path.getsize 和 Content-Length 比对再跑一次 MD5对不上就删除重下。无人值守脚本里这一条是基本素养。4.3 下载卡住不动既不报错也不结束现象脚本停在原地进度百分比不动CtrlC 之后 traceback 停在 iter_content 的读取那一行看起来什么都没做。原因九成是 timeout 没设全。要么没写 timeout要么只写了一个数字。连接建立后服务器一直不发数据TCP 层面没有任何错误信号读超时又是 None代码就无限等下去。某些 CDN 边缘节点回源慢时会出现这种连接在了但数据不来的情况。解决timeout 设成 (connect, read) 二元组read 给 60 秒。再套一层总时长护栏记录开始时间在循环里判断 elapsed超过上限主动抛异常退出。读超时是数据块之间空闲时间的上限不是总时长这个语义在第 3.1 节已经强调过这里是它最典型的应用场景。4.4 服务器返回 403浏览器却能正常下载现象同一个 URL浏览器右键另存为没问题脚本一跑就是 403 Forbidden响应体是一个不说明任何问题的错误页。原因服务器在检测客户端。requests 默认 UA 是 python-requests/2.x.x特征太明显很多下载服务器直接拒绝。另一种情况是校验 Referer要求请求必须携带特定页面跳转的来源裸请求没有这个头。解决先把 User-Agent 换成浏览器的完整 UA一半以上的 403 到此解决。还不行就打开浏览器开发者工具的 Network 面板重新触发一次下载把那次请求的 User-Agent、Referer、Accept、Cookie 原样复制进脚本。涉及登录态的资源用 requests.Session() 先走登录流程让 Session 把 Cookie 带上再发起下载。4.5 断点续传续出来一个坏文件现象下载中断后重跑脚本任务显示完成但文件校验失败打开一看开头是乱码或者文件大小比预期大了一截。原因文件打开模式写错。服务器接受 Range 返回 206应该用 ab 追加服务器不支持 Range 返回 200 全量内容必须用 wb 覆盖。很多人只写了 ab在服务器不支持 Range 的场景下新内容被追加到旧文件尾部中间还缺一段文件直接废掉。解决根据 status_code 决定模式206 追加、200 覆盖代码见第 3.4 节。续传完成后用已写入字节数加 206 响应的 Content-Length 去和预期总大小比对最后跑一次 MD5。续传逻辑越复杂越需要一个最终校验兜底这条不要省。提示文件名乱码不在上面五条里但遇到概率很高。解析优先级是 filename*UTF-8 优先退回 filename再退回 URL 末段拿到后先 unquote 解码、再 os.path.basename 过滤代码模板在第 3.3 节。5. 把下载器做成能用的工具进度显示与多文件并行前面章节解决能不能下完这一章给一个抄完就能跑的下载器模板把进度显示和多文件并发合在一起。5.1 带进度显示的下载函数import sys import requests def download_one(session, url, filepath): resp session.get(url, streamTrue, timeout(5, 60), headers{ User-Agent: Mozilla/5.0, Accept-Encoding: identity, }) resp.raise_for_status() total int(resp.headers.get(Content-Length, 0)) done 0 with open(filepath, wb) as f: for chunk in resp.iter_content(chunk_size65536): if not chunk: continue f.write(chunk) done len(chunk) if total: sys.stdout.write(f\r{filepath}: {done / total * 100:.1f}%) sys.stdout.flush() print(f\n{filepath} 完成共 {done} 字节)参数说明session 由外部传入多文件并发时复用连接池Content-Length 为 0 时跳过百分比只显示已下载字节数\r 让进度在同一行刷新不刷屏。total 拿不到时部分服务器不返回 Content-Length进度条会自动降级成字节计数不影响功能。5.2 并发入口ThreadPoolExecutorfrom concurrent.futures import ThreadPoolExecutor, as_completed from requests import Session urls { https://example.com/files/a.zip: a.zip, https://example.com/files/b.zip: b.zip, https://example.com/files/c.zip: c.zip, } session Session() with ThreadPoolExecutor(max_workers4) as pool: futures {pool.submit(download_one, session, u, p): u for u, p in urls.items()} for fut in as_completed(futures): try: fut.result() except Exception as e: print(f{futures[fut]} 失败: {e})参数说明max_workers 建议 4 到 6下载是 I/O 密集操作线程完全够用不需要上多进程worker 开太多会被服务器限速甚至封禁。Session 是线程安全的可以放心在多个线程间共享它会自动复用底层 TCP 连接避免每个文件都重新握手。这套模板是我现在写下载脚本的标准开头加校验、加断点续传、加限速都在这个骨架上扩展。我最早写下载脚本时内存爆过、续传续出过坏文件、403 卡了半天才反应过来是 UA 的问题后来把超时、重试、校验这三件事固化进模板才踏实下来。这个方向值不值得投入我的判断很简单只要你的下载脚本要离开本地手跑、进入服务器或定时任务第 3 章和第 4 章讲的每一件事都值得现在就补上。希望帮到你。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
