HTTP 下载器

相关源文件

• youtube_dl/downloader/common.py
• youtube_dl/downloader/dash.py
• youtube_dl/downloader/f4m.py
• youtube_dl/downloader/fragment.py
• youtube_dl/downloader/hls.py
• youtube_dl/downloader/http.py
• youtube_dl/downloader/ism.py
• youtube_dl/downloader/rtmp.py
• youtube_dl/extractor/audioboom.py
• youtube_dl/extractor/karrierevideos.py
• youtube_dl/extractor/radiobremen.py
• youtube_dl/extractor/rtl2.py

HTTP 下载器是 youtube-dl 下载系统中的核心组件，负责通过 HTTP 和 HTTPS 协议获取媒体文件。它提供了强大的基础文件下载功能，包括可续传性、速率限制和错误处理。对于 HLS、DASH 或 RTMP 等专用媒体格式，请参阅 碎片媒体下载器 中的相应下载器。

概述

HTTP 下载器实现为 HttpFD，它是抽象的 FileDownloader 类的子类。它处理标准的 HTTP/HTTPS 文件下载过程，管理连接、跟踪进度，并在从 Web 服务器下载内容时处理错误。

下载器系统层级中的 HTTP 下载器

来源： youtube_dl/downloader/http.py youtube_dl/downloader/common.py youtube_dl/downloader/fragment.py youtube_dl/downloader/hls.py youtube_dl/downloader/dash.py youtube_dl/downloader/f4m.py youtube_dl/downloader/rtmp.py youtube_dl/downloader/ism.py

HTTP 下载过程

HTTP 下载器负责 HTTP 下载的整个生命周期，从建立连接到完成下载文件。核心工作流程包括以下主要阶段：

来源： youtube_dl/downloader/http.py28-362

下载上下文

HTTP 下载器使用 DownloadContext 字典状对象来维护下载过程中的状态。此上下文包含：

• 文件名（目标和临时）
• 续传信息
• 流句柄
• 进度跟踪数据
• 块大小和分块大小设置

来源： youtube_dl/downloader/http.py31-34

连接建立

establish_connection 函数处理：

1. 设置带有适当标头的 HTTP 请求
2. 处理 Range 请求以实现可续传下载
3. 处理服务器响应以确定是否可以续传
4. 检索内容长度信息

如果请求了续传但服务器不支持，下载器将从头开始。

来源： youtube_dl/downloader/http.py86-196

下载进程

主要的 download 函数管理：

1. 从连接中按块读取数据
2. 将数据写入文件
3. 跟踪下载进度
4. 速率限制以符合带宽限制
5. 动态调整块大小以实现最佳吞吐量
6. 通过钩子报告进度

来源： youtube_dl/downloader/http.py197-346

主要功能

可续传下载

HTTP 下载器支持恢复部分下载的文件，这对于大型媒体文件特别有用。此功能由 continuedl 参数控制，工作方式是：

1. 检查是否存在部分文件
2. 确定其大小
3. 设置 Range HTTP 标头以仅请求剩余部分
4. 通过 Content-Range 标头验证服务器响应是否支持 Range 请求

此功能对于在不从头开始的情况下恢复中断的下载至关重要。

来源： youtube_dl/downloader/http.py59-147

速率限制

速率限制可防止下载器充分利用可用带宽

1. ratelimit 参数指定每秒最大字节数
2. 处理完每个块后会调用 slow_down 方法
3. 如果当前下载速度超过限制，该方法会引入延迟

来源： youtube_dl/downloader/common.py177-191

分块下载

HTTP 下载器通过 http_chunk_size 参数支持分块下载

1. 指定时，下载将被拆分为多个 HTTP 请求
2. 每个请求下载指定大小的块
3. 这有助于绕过某些 Web 服务器施加的带宽限制

此功能通过使用 Range 标头请求特定的字节范围，然后将这些块合并为完整文件来实现。

来源： youtube_dl/downloader/http.py87-100 youtube_dl/downloader/http.py313-316

动态块大小调整

为了优化下载性能，HTTP 下载器会根据下载速度动态调整块大小

1. 初始块大小设置为配置的 buffersize 参数（默认：1024 字节）
2. 每个块处理后，计算下载速度
3. 块大小会调整为匹配当前速度，并在定义的限制范围内
4. 此优化可以通过 noresizebuffer 参数禁用

来源： youtube_dl/downloader/common.py136-147 youtube_dl/downloader/http.py289-292

错误处理

HTTP 下载器实施了强大的错误处理机制，以应对各种网络问题

重试机制

下载器将根据 retries 参数重试失败的下载

1. HTTP 错误（尤其是 5xx 错误）
2. 连接重置和超时
3. 内容长度不匹配

当需要重试时，下载器会报告错误，在必要时等待，然后再次尝试下载。

来源： youtube_dl/downloader/http.py347-361 youtube_dl/downloader/http.py149-195

内容验证

下载完成后，下载器会验证接收到的内容是否与预期大小匹配

1. 如果服务器提供了 Content-Length 标头，下载器会将其与实际下载的字节数进行比较
2. 如果不匹配，将引发 ContentTooShortError，可能会触发重试

此验证有助于确保下载内容的完整性。

来源： youtube_dl/downloader/http.py325-329

配置选项

HTTP 下载器支持许多控制其行为的配置选项

选项	描述	默认
buffersize	下载缓冲区大小（字节）	1024
continuedl	尽可能尝试继续下载	True
http_chunk_size	分块下载的块大小	0 (禁用)
noprogress	不要打印进度条	否
noresizebuffer	不要自动调整下载缓冲区大小	否
ratelimit	下载速度限制（字节/秒）	None
retries	针对 HTTP 错误 5xx 的重试次数	0
test	仅下载前几个字节以测试下载器	否
min_filesize	跳过小于此大小的文件	None
max_filesize	跳过大于此大小的文件	None
updatetime	使用 Last-modified 标头设置输出文件时间戳	True
xattr_set_filesize	使用预期的文件大小设置 ytdl.filesize 用户 xattribute	否

这些选项可以在传递给 FileDownloader 构造函数的 params 字典中设置。

来源： youtube_dl/downloader/common.py20-56

与其他组件的集成

HTTP下载器集成了youtube-dl的其他组件

来源： youtube_dl/downloader/common.py youtube_dl/downloader/http.py youtube_dl/downloader/fragment.py145-156

由片段下载器使用

HTTP下载器被基于片段的下载器（如FragmentFD及其子类）用作

1. HttpQuietDownloader - 一种抑制输出的专用版本
2. 处理 HLS、DASH 和 F4M 等分段格式中的单个片段下载

这种关系使专用下载器能够利用强大的 HTTP 下载功能，同时实现其自身的格式特定逻辑。

来源： youtube_dl/downloader/fragment.py17-19 youtube_dl/downloader/fragment.py145-156

进度报告

HTTP下载器通过钩子机制报告下载进度

1. 可以通过 add_progress_hook 注册进度钩子
2. 下载状态通过以下指标报告，包括
   • 下载的字节数
   • 总字节数（如果已知）
   • 下载速度
   • 预计到达时间
   • 状态（下载中/完成）

此信息用于向用户显示进度条和其他反馈。

来源： youtube_dl/downloader/http.py296-308 youtube_dl/downloader/common.py258-317