做技术的人多少都遇到过这样的时刻看到一个公开的教程视频、技术分享或者一段自己参与录制的培训录像想保存到本地慢慢看结果找了一圈工具不是捆绑软件满天飞就是下载到一半提示要开会员。其实基于yt-dlpFFmpeg的命令行下载方案完全可以打造一个轻量、稳定、可自动化的“视频下载神器”。本文会从原理讲起再给出完整的封装脚本和常见问题排查清单适合想自建视频下载工具的开发者参考。这类工具的价值并不在于“绕过什么限制”而在于把分散在不同公开页面上的视频批量、按规则、可复现地归档到本地。比如技术团队内部的知识库视频、公开课程回放、个人录制素材、演示录像等场景都非常适合用命令行工具来完成。相比手动打开浏览器逐个下载命令行方式更适合写进脚本、接进 CI/CD 流程甚至做成定时任务长期维护成本低很多。1. 背景与核心概念1.1 视频下载工具解决什么问题很多人以为视频下载就是把一个.mp4文件另存到本地。但实际情况复杂得多不少网页中的视频并不是单一文件而是被拆成了多个分片有些是音频和视频分离的播放器在网页端实时合成有些需要带用户身份信息才能访问还有些需要解析不同清晰度对应的地址。如果直接打开浏览器开发者工具去翻网络请求手动拼 URL效率极低且容易失效。视频下载工具的核心价值就是把“解析页面内容、识别媒体地址、按清晰度选择、合并音视频、保存到本地”这套流程自动化。用户只需要提供一个页面地址工具会自动分析页面结构提取出所有可下载的媒体流然后按照用户指定的规则下载。基于yt-dlp的 Python 项目本质上是把上游命令行工具的能力封装成更贴合个人需要的下载器。1.2 为什么选中 yt-dlp 而不是其它工具在开源社区youtube-dl是很早出现的命令行视频下载工具但后续更新节奏变慢于是社区维护者派生了yt-dlp。yt-dlp对更多网站做了适配下载速度更快支持的功能更丰富比如下载片段、提取字幕、按播放列表批量下载、读取浏览器 Cookie 等。它的核心优点可以概括为支持数百个网站的媒体地址解析命令行参数设计清晰脚本友好提供 Python API方便二次开发内置 FFmpeg 联动可以自动合并音视频流支持分段并发下载明显提升大文件下载效率。本文不会把重点放在介绍某些特定网站的抓取规则上而是讲解如何使用这套开源工具链搭建一个属于自己的通用下载器。你可以拿它下载正常的公开视频也可以把思路迁移到内部系统的视频归档场景。1.3 关键依赖FFmpeg 到底起什么作用FFmpeg 是一个强大的多媒体处理框架处理视频转码、音频提取、视频剪辑、格式封装等任务。在 yt-dlp 的工作流程里FFmpeg 通常做两件事一是把分离的视频流和音频流合并成带声音的完整文件二是把下载的流转换为指定封装格式比如从webm转为mp4。如果电脑上没有安装 FFmpegyt-dlp 依然能下载部分单文件视频但遇到“视频无声”或“格式受限”的情况就会失败。很多新手下载后的视频没有声音问题就出在 FFmpeg 缺失或没被正确识别。所以搭建这个工具链的第一步不是写脚本而是把 Python、yt-dlp、FFmpeg 这三个基础组件装好。1.4 合规与版权提醒在使用任何视频下载工具时需要明确一条边界只下载自己拥有权限的内容例如公开授权的教程、开源平台上的演示视频、自己团队内部上传的培训录像、已获得授权允许离线保存的资料。不要把工具用于绕过付费墙、破解会员、爬取他人私有内容等用途。技术本身是中性的但使用场景必须合法合规。本文示例只用于学习和个人合法备份目的。2. 环境准备与版本说明2.1 基础环境要求在动手之前先确认你的电脑上具备以下基础环境操作系统Windows 10/11、macOS、Linux 均可本文以 Windows 和 Linux 为主Python 版本推荐 3.8 或更高版本yt-dlp对 Python 3.7 以上的兼容性较好但较新的版本可能需要更高 Python 版本支撑FFmpeg建议安装最新稳定版命令行工具Windows 使用 PowerShell 或 CMDmacOS/Linux 使用 Terminal。版本说明由于yt-dlp迭代很快依赖的网站解析规则经常变化因此建议始终升级到最新版本而不是锁定某个旧版本长期使用。文中涉及的参数和命令基于当前通用版本如果你使用的版本较旧个别参数可能略有差异建议先运行yt-dlp --version查看版本。2.2 安装 yt-dlp最简单的方式是使用 pip 安装pip install -U yt-dlpWindows 用户注意如果安装完成后在终端输入yt-dlp提示“不是内部或外部命令”说明 Python 的 Scripts 目录没有加入系统 PATH。可以在安装输出中找到 Scripts 路径或者在 Visual Studio Code 中重新打开终端。建议安装后先验证版本yt-dlp --version除了 pip还可以从 GitHub Releases 页面下载对应的二进制包Windows 用户可以把yt-dlp.exe放到任意目录后将该目录加入 PATH。macOS 用户也可以用 Homebrew 安装brew install yt-dlp2.3 安装 FFmpegFFmpeg 的安装方式按系统区分Windows 用户下载 FFmpeg 的 Windows 版本后解压到某个路径例如C:\ffmpeg。然后把C:\ffmpeg\bin加入系统环境变量 PATH。打开 PowerShell输入以下命令验证ffmpeg -version如果能看到版本信息说明安装成功。macOS 用户brew install ffmpegLinux 用户以 Ubuntu/Debian 为例sudo apt update sudo apt install ffmpegFFmpeg 安装完成之后yt-dlp 内部会自动识别ffmpeg命令。如果你把 FFmpeg 安装到了特殊目录也可以通过 yt-dlp 的--ffmpeg-location参数指定路径。2.4 示例项目结构为了后续封装脚本我们先规划一个项目结构。这个结构不是必须的但合理的目录组织可以让脚本更易于维护。video-downloader/ ├── downloader.py # 核心下载脚本 ├── batch_urls.txt # 批量下载的链接列表 ├── output/ # 视频输出目录 │ ├── videos/ │ └── logs/ └── config.ini # 可选配置文件在后面的实战部分我们会逐步实现这个项目中的核心脚本。3. 核心命令与参数拆解3.1 基础下载命令先用最简单的命令测试工具是否正常工作。例如下载一个公开视频yt-dlp https://www.example.com/watch/12345命令执行后yt-dlp 会解析页面内容找到视频流并下载到当前目录。默认情况下它会自动选择可用的最佳画质。不过这里有一个需要理解的点很多网站的“最佳画质”是音视频分离的两个流yt-dlp 需要调用 FFmpeg 合并所以要确保 FFmpeg 已安装。3.2 列出所有可用格式在正式下载之前通常先用-F参数查看页面提供的所有媒体流yt-dlp -F URL输出内容会列出每一个格式的编号、扩展名、分辨率、码率等信息。比如类似下面这样ID EXT RESOLUTION FORMAT INFO 18 mp4 640x360 1440K mp4, avc1.42001E, 30fps, video only 22 mp4 1280x720 2780K mp4, avc1.64001F, 30fps, video only 140 m4a audio only m4a, mp4a.40.2, 128K, audio only这个信息非常关键因为不同网站的编码方案差异很大。有些视频流可能是webm格式有些可能是m4a音频流。通过-F查看以后你就能清楚地知道当前页面提供了哪些可下载的资源。3.3 选择指定清晰度并合并当视频和音频分离时可以组合选择。例如yt-dlp -f bv[height1080]ba/b[height1080] --merge-output-format mp4 URL参数解释bv表示 best video即最佳视频流[height1080]表示限制高度不超过 1080ba表示 best audio即最佳音频流表示将视频流和音频流合并最后面的b[height1080]是兜底方案如果上面组合失败就选一个包含音视频的较佳整体文件--merge-output-format mp4指定合并后的输出格式为 MP4。这个组合方式在实际项目中非常常用它能保证下载的视频不超过 1080p并且不会出现“有画无声”的情况。3.4 指定输出目录与文件名模板默认输出文件名不够清晰建议使用-o参数自定义模板yt-dlp -o %(title)s.%(ext)s URL更规范的模板可以包含上传者、日期、清晰度等信息yt-dlp -o output/videos/%(uploader)s/%(date)s_%(title)s_%(height)sp.%(ext)s URL这里的%(字段名)s是由 yt-dlp 提供的输出模板变量支持的字段包括title、uploader、id、upload_date、height、ext等。这些变量可以在脚本中组合使用让下载文件归档到合理的目录结构里。3.5 下载字幕与缩略图如果视频包含字幕可以加上--write-subs --write-auto-subs参数。--write-subs写入普通字幕--write-auto-subs写入自动生成字幕。还可以用--sub-langs指定字幕语言。缩略图则通过--write-thumbnail参数下载。yt-dlp --write-subs --write-auto-subs --sub-langs zh-Hans,en --write-thumbnail URL字幕文件默认与视频同名但扩展名不同例如.vtt或.srt。如果你希望把字幕嵌入视频文件则需要使用 FFmpeg 相关参数但那属于更进阶的用法本文先不展开。3.6 限速与断点续传下载大文件时如果担心占用带宽可以限制速度yt-dlp --limit-rate 2M URL--limit-rate的单位可以是K、M等。yt-dlp 默认支持断点续传如果下载中断重新执行同样的命令它往往能从断点处继续不需要额外参数。对于不完整的文件也可以使用--continue强制开启续传但多数情况下默认行为已经足够好。3.7 批量下载与播放列表如果有多个链接可以创建一个文本文件把链接逐行写入然后使用-a参数批量下载yt-dlp -a batch_urls.txt批量模式下稍加扩展就能做到逐个下载并记录日志。对于支持播放列表的网站urllib 或 yt-dlp 会自动识别播放列表中的所有视频默认会全部下载。如果只想下载最近几个可以用--playlist-items 1-5限制范围。--playlist-end 10则可以限制最多下载 10 个视频。4. 完整实战案例用 Python 封装一个“视频下载神器”4.1 需求分析直接使用命令行已经能满足大部分需求但为了长期使用我们还需要解决几个问题链接多的时候手动输入命令太麻烦下载失败需要自动重试日志需要持久化方便排查问题输出目录需要按日期和来源自动整理最好支持从配置文件读取参数而不是每次修改命令。基于这些需求我们编写一个 Python 脚本把 yt-dlp 封装成可复用的下载工具。脚本主要包含四个模块参数解析、链接读取、下载执行、日志记录。4.2 创建项目结构在本地新建目录video-downloader按下面的结构创建文件video-downloader/ ├── downloader.py # 主脚本 ├── batch_urls.txt # 批量链接 ├── output/ │ ├── videos/ │ └── logs/在output目录下创建videos和logs两个子目录用于存放视频文件与日志文件。4.3 核心代码实现我们先实现downloader.py。这个脚本的功能包括读取命令行传入的单个链接或者批量文件调用 yt-dlp 下载视频对下载结果进行简单重试生成带时间戳的日志文件。# 文件路径video-downloader/downloader.py import argparse import logging import subprocess import sys import time from pathlib import Path BASE_DIR Path(__file__).resolve().parent VIDEO_DIR BASE_DIR / output / videos LOG_DIR BASE_DIR / output / logs VIDEO_DIR.mkdir(parentsTrue, exist_okTrue) LOG_DIR.mkdir(parentsTrue, exist_okTrue) logging.basicConfig( levellogging.INFO, format%(asctime)s [%(levelname)s] %(message)s, handlers[ logging.StreamHandler(sys.stdout), logging.FileHandler(LOG_DIR / fdownload-{time.strftime(%Y%m%d-%H%M%S)}.log, encodingutf-8) ] ) logger logging.getLogger(video-downloader) def read_urls_from_file(file_path: Path) - list[str]: 从文本文件逐行读取链接忽略空行和注释行。 if not file_path.exists(): logger.error(链接文件不存在: %s, file_path) return [] urls [] for line in file_path.read_text(encodingutf-8).splitlines(): line line.strip() if not line or line.startswith(#): continue urls.append(line) logger.info(从文件读取到 %d 个链接, len(urls)) return urls def download_video(url: str, output_dir: Path, max_retry: int 3) - bool: 使用 yt-dlp 下载单个视频并支持失败重试。 参数说明: url: 视频页面地址 output_dir: 视频输出目录 max_retry: 最大重试次数 返回: bool 表示是否下载成功 cmd [ yt-dlp, --newline, -f, bv[height1080]ba/b[height1080], --merge-output-format, mp4, -o, str(output_dir / %(uploader)s/%(date)s_%(title)s_%(height)sp.%(ext)s), --write-subs, --write-auto-subs, --sub-langs, zh-Hans,en, --limit-rate, 8M, url ] for attempt in range(1, max_retry 1): logger.info(开始下载: %s (第 %d 次尝试), url, attempt) result subprocess.run(cmd, textTrue, encodingutf-8, errorsreplace) if result.returncode 0: logger.info(下载成功: %s, url) return True logger.warning(下载失败准备重试: %s, url) time.sleep(attempt * 2) logger.error(多次重试后仍然失败: %s, url) return False def main(): parser argparse.ArgumentParser(description基于 yt-dlp 的批量视频下载工具) group parser.add_mutually_exclusive_group(requiredTrue) group.add_argument(-u, --url, help单个视频链接) group.add_argument(-f, --file, help批量链接文件路径默认读取 batch_urls.txt) args parser.parse_args() if args.url: urls [args.url] else: file_path Path(args.file) if args.file else BASE_DIR / batch_urls.txt urls read_urls_from_file(file_path) if not urls: logger.error(没有可下载的链接程序退出) sys.exit(1) success_count 0 for i, url in enumerate(urls, start1): logger.info(进度: %d/%d, i, len(urls)) if download_video(url, VIDEO_DIR): success_count 1 logger.info(全部处理完成成功 %d 个失败 %d 个, success_count, len(urls) - success_count) if __name__ __main__: main()4.4 代码要点说明脚本中有几处值得注意的设计使用subprocess.run调用系统命令而不是通过 Python 的 SDK 初始化方式可以避免依赖 API 版本变化--newline参数让 yt-dlp 在下载过程中输出实时进度方便在日志里看到进度输出模板中包含%(uploader)s这样不同来源的视频会自动按上传者分目录重试策略采用递增等待时间避免失败后立即重试导致被网站限流日志同时输出到控制台和文件文件日志会带上时间戳方便追溯历史下载记录。4.5 配置化改进把常用参数放到配置文件中更便于维护。这里不引入复杂的配置库直接用 Python 内置的configparser来读取一个简单的config.ini文件。; 文件路径video-downloader/config.ini [download] format bv[height1080]ba/b[height1080] merge_format mp4 output_template output/videos/%(uploader)s/%(date)s_%(title)s_%(height)sp.%(ext)s limit_rate 8M write_subs true sub_langs zh-Hans,en然后在downloader.py中增加读取配置的逻辑。核心思路是默认参数从配置文件读取命令行参数优先级更高。由于篇幅原因这里只展示配置读取的关键片段# 文件路径video-downloader/downloader.py配置读取片段 import configparser def load_config() - configparser.ConfigParser: config configparser.ConfigParser() config_path BASE_DIR / config.ini if config_path.exists(): config.read(config_path, encodingutf-8) return config这样日常使用中只需要维护config.ini和batch_urls.txt不需要频繁修改脚本文件。4.6 运行与验证首先创建一个batch_urls.txt每行一个链接# 这是示例链接请替换成你有权限下载的视频地址 https://www.example.com/media/001 https://www.example.com/media/002然后在项目根目录执行python downloader.py -f batch_urls.txt或者只下载单个链接python downloader.py -u https://www.example.com/media/001程序运行后控制台会输出类似下面的日志2025-01-15 14:30:00,123 [INFO] 从文件读取到 2 个链接 2025-01-15 14:30:00,124 [INFO] 进度: 1/2 2025-01-15 14:30:00,125 [INFO] 开始下载: https://www.example.com/media/001 (第 1 次尝试) 2025-01-15 14:30:26,880 [INFO] 下载成功: https://www.example.com/media/001下载完成后进入output/videos目录可以看到按上传者/日期命名的视频文件。日志文件则保存在output/logs下。5. 常见问题与排查思路用 yt-dlp 搭建下载工具的过程中新手最容易卡在几个固定的报错上。这里整理一份实用的排查表。问题现象常见原因解决思路提示yt-dlp 不是内部或外部命令Python Scripts 目录未加入 PATH或安装后未重启终端重新打开终端或找到 Scripts 路径加入环境变量下载后视频没有声音视频流和音频流分离但 FFmpeg 缺失安装 FFmpeg并确认ffmpeg -version可用报错HTTP Error 403网站要求登录或做了访问限制使用--cookies-from-browser chrome读取浏览器登录态报错Unsupported URL链接格式不被支持或 yt-dlp 版本太旧检查链接是否为公开可访问页面并升级 yt-dlp下载速度很慢服务端限制单连接速度或网络链路质量不稳定使用--limit-rate降低预期或适当提高分段并发数文件下载到一半失败网络中断、服务器断开连接、磁盘空间不足检查磁盘空间利用默认断点续传重新执行命令合并 MP4 失败FFmpeg 版本过旧或格式不支持直接封装升级 FFmpeg尝试改用mkv格式5.1 输出日志只有标题没有进度条如果脚本中使用了--newline正常情况下会有逐行进度输出。如果看不到很可能是 yt-dlp 检测到非终端环境自动关闭了进度显示。这时不要慌程序仍然在正常工作只是没有可视化进度。可以在日志中记录开始和结束时间用来判断任务是否完成。5.2 下载 1080p 视频时视频和音频不同步多数情况下yt-dlp 合并后的音视频是同步的。如果出现不同步常见原因是编码参数差异过大或者视频流与音频流来自不同的编码器。可以先尝试升级 FFmpeg因为新版 FFmpeg 对时间戳处理更完善。如果问题依旧可以尝试下载整体文件中质量较高的单一文件格式也就是使用-f b[height1080]避免音视频合并流程。5.3 如何获取需要登录的视频如果视频需要登录后才可访问yt-dlp 提供了从浏览器读取 Cookie 的方式。最常用的是yt-dlp --cookies-from-browser chrome URL这里要注意浏览器必须处于未彻底退出登录的状态因为 yt-dlp 会读取浏览器本地的 Cookie 数据库。使用该功能时请确保你有权访问目标视频且操作符合网站的服务条款。对敏感账号信息建议在专用的测试浏览器环境中操作避免引发安全问题。5.4 输出文件名为乱码或包含不合法字符Windows 文件名不支持/、\、:、*、?、、、、|等字符。yt-dlp 的sanitize_filename函数会自动清理大部分不合法字符。如果仍遇到问题建议在输出模板中加入视频id字段例如-o %(id)s_%(title)s.%(ext)s或者直接在 Python 脚本中二次处理文件名把不合法字符替换掉。6. 最佳实践与工程建议6.1 把下载器设计成幂等任务在工程实践中下载脚本最好具备幂等性。也就是说同一个链接无论执行多少次结果都应该一致。通过固定的输出模板和文件名包含视频 id可以避免重复下载时生成多个副本。虽然 yt-dlp 检测到文件存在时会跳过但增加 id 会更精确因为不同页面上的标题可能完全一样。6.2 日志分级与日志持久化日志不要只打在控制台最好同时写入文件。建议按日期切分日志保留最近 7 到 30 天的日志文件。日志级别上INFO 记录下载 URL 和成功失败状态WARNING 记录重试和异常ERROR 记录最终失败。这样定位问题时能快速从大文件中找到有效信息。6.3 重试策略与退避网络下载的不确定性很高失败重试是必须的。但重试不能太频繁建议采用指数退避策略第一次失败后等 2 秒第二次等 4 秒第三次等 8 秒最多重试 3 到 5 次。如果仍然失败就把链接写入失败队列供后续人工处理。6.4 磁盘空间与文件清理视频文件通常很大连续批量下载前要检查磁盘剩余空间。可以在脚本中增加磁盘检查逻辑当剩余空间低于阈值时停止任务。另外建议定期把下载完成且确认无误的文件移动到长期存储设备保持下载目录可控。6.5 定时任务与无人值守在 Linux 或 macOS 上可以通过crontab设置定时任务比如每天凌晨 3 点执行一次下载脚本。Windows 上可以使用任务计划程序。定时任务场景下需要特别注意日志和错误通知。建议脚本在任务结束时生成退出码如果连续失败可以通过邮件、企业微信或钉钉机器人推送提醒。6.6 安全与权限最小化下载工具可能需要读取浏览器 Cookie这会涉及到账号凭证。建议在专用机器上运行而不是随意在公共电脑上使用。如果脚本会在服务器上运行给脚本创建一个专属系统用户不要使用 root 或管理员账号。配置文件中的敏感信息要设置严格的文件权限避免被其他用户读取。7. 总结与学习路线通过本文的实践你应该已经掌握了一条完整的视频下载工具链安装 Python、yt-dlp 和 FFmpeg理解 yt-dlp 常用的-F、-f、-o、--merge-output-format等参数然后用 Python 封装了支持批量、日志、重试的下载脚本。这套工具从功能上已经算得上一个合格的“视频下载神器”。接下来可以继续学习的方向包括使用 yt-dlp 的 Python API 替代 subprocess 调用实现对下载进度的更精细控制增加定时任务和失败通知构建完整的无人值守下载系统结合 FFmpeg 做视频后处理比如转码、截图、拼接、提取音频设计 Web 管理界面通过网页提交下载任务适合团队内部使用研究不同站点媒体流的编码格式差异更好地理解 HLS、DASH 等流媒体协议。在实际项目中优先关注三点一是始终升级 yt-dlp因为网站页面结构经常变化二是保证 FFmpeg 环境稳定否则合并不了音视频三是做好日志和磁盘空间管理避免长时间运行后磁盘被占满。视频下载工具本身并不复杂但把它做成稳定、可维护、自动化的小系统则需要工程化思维。如果你动手把脚本跑起来并尝试改造成自己需要的版本相信很快就能体会到命令行工具的乐趣。 使用yt-dlp与FFmpeg打造命令行视频下载神器
做技术的人多少都遇到过这样的时刻看到一个公开的教程视频、技术分享或者一段自己参与录制的培训录像想保存到本地慢慢看结果找了一圈工具不是捆绑软件满天飞就是下载到一半提示要开会员。其实基于yt-dlpFFmpeg的命令行下载方案完全可以打造一个轻量、稳定、可自动化的“视频下载神器”。本文会从原理讲起再给出完整的封装脚本和常见问题排查清单适合想自建视频下载工具的开发者参考。这类工具的价值并不在于“绕过什么限制”而在于把分散在不同公开页面上的视频批量、按规则、可复现地归档到本地。比如技术团队内部的知识库视频、公开课程回放、个人录制素材、演示录像等场景都非常适合用命令行工具来完成。相比手动打开浏览器逐个下载命令行方式更适合写进脚本、接进 CI/CD 流程甚至做成定时任务长期维护成本低很多。1. 背景与核心概念1.1 视频下载工具解决什么问题很多人以为视频下载就是把一个.mp4文件另存到本地。但实际情况复杂得多不少网页中的视频并不是单一文件而是被拆成了多个分片有些是音频和视频分离的播放器在网页端实时合成有些需要带用户身份信息才能访问还有些需要解析不同清晰度对应的地址。如果直接打开浏览器开发者工具去翻网络请求手动拼 URL效率极低且容易失效。视频下载工具的核心价值就是把“解析页面内容、识别媒体地址、按清晰度选择、合并音视频、保存到本地”这套流程自动化。用户只需要提供一个页面地址工具会自动分析页面结构提取出所有可下载的媒体流然后按照用户指定的规则下载。基于yt-dlp的 Python 项目本质上是把上游命令行工具的能力封装成更贴合个人需要的下载器。1.2 为什么选中 yt-dlp 而不是其它工具在开源社区youtube-dl是很早出现的命令行视频下载工具但后续更新节奏变慢于是社区维护者派生了yt-dlp。yt-dlp对更多网站做了适配下载速度更快支持的功能更丰富比如下载片段、提取字幕、按播放列表批量下载、读取浏览器 Cookie 等。它的核心优点可以概括为支持数百个网站的媒体地址解析命令行参数设计清晰脚本友好提供 Python API方便二次开发内置 FFmpeg 联动可以自动合并音视频流支持分段并发下载明显提升大文件下载效率。本文不会把重点放在介绍某些特定网站的抓取规则上而是讲解如何使用这套开源工具链搭建一个属于自己的通用下载器。你可以拿它下载正常的公开视频也可以把思路迁移到内部系统的视频归档场景。1.3 关键依赖FFmpeg 到底起什么作用FFmpeg 是一个强大的多媒体处理框架处理视频转码、音频提取、视频剪辑、格式封装等任务。在 yt-dlp 的工作流程里FFmpeg 通常做两件事一是把分离的视频流和音频流合并成带声音的完整文件二是把下载的流转换为指定封装格式比如从webm转为mp4。如果电脑上没有安装 FFmpegyt-dlp 依然能下载部分单文件视频但遇到“视频无声”或“格式受限”的情况就会失败。很多新手下载后的视频没有声音问题就出在 FFmpeg 缺失或没被正确识别。所以搭建这个工具链的第一步不是写脚本而是把 Python、yt-dlp、FFmpeg 这三个基础组件装好。1.4 合规与版权提醒在使用任何视频下载工具时需要明确一条边界只下载自己拥有权限的内容例如公开授权的教程、开源平台上的演示视频、自己团队内部上传的培训录像、已获得授权允许离线保存的资料。不要把工具用于绕过付费墙、破解会员、爬取他人私有内容等用途。技术本身是中性的但使用场景必须合法合规。本文示例只用于学习和个人合法备份目的。2. 环境准备与版本说明2.1 基础环境要求在动手之前先确认你的电脑上具备以下基础环境操作系统Windows 10/11、macOS、Linux 均可本文以 Windows 和 Linux 为主Python 版本推荐 3.8 或更高版本yt-dlp对 Python 3.7 以上的兼容性较好但较新的版本可能需要更高 Python 版本支撑FFmpeg建议安装最新稳定版命令行工具Windows 使用 PowerShell 或 CMDmacOS/Linux 使用 Terminal。版本说明由于yt-dlp迭代很快依赖的网站解析规则经常变化因此建议始终升级到最新版本而不是锁定某个旧版本长期使用。文中涉及的参数和命令基于当前通用版本如果你使用的版本较旧个别参数可能略有差异建议先运行yt-dlp --version查看版本。2.2 安装 yt-dlp最简单的方式是使用 pip 安装pip install -U yt-dlpWindows 用户注意如果安装完成后在终端输入yt-dlp提示“不是内部或外部命令”说明 Python 的 Scripts 目录没有加入系统 PATH。可以在安装输出中找到 Scripts 路径或者在 Visual Studio Code 中重新打开终端。建议安装后先验证版本yt-dlp --version除了 pip还可以从 GitHub Releases 页面下载对应的二进制包Windows 用户可以把yt-dlp.exe放到任意目录后将该目录加入 PATH。macOS 用户也可以用 Homebrew 安装brew install yt-dlp2.3 安装 FFmpegFFmpeg 的安装方式按系统区分Windows 用户下载 FFmpeg 的 Windows 版本后解压到某个路径例如C:\ffmpeg。然后把C:\ffmpeg\bin加入系统环境变量 PATH。打开 PowerShell输入以下命令验证ffmpeg -version如果能看到版本信息说明安装成功。macOS 用户brew install ffmpegLinux 用户以 Ubuntu/Debian 为例sudo apt update sudo apt install ffmpegFFmpeg 安装完成之后yt-dlp 内部会自动识别ffmpeg命令。如果你把 FFmpeg 安装到了特殊目录也可以通过 yt-dlp 的--ffmpeg-location参数指定路径。2.4 示例项目结构为了后续封装脚本我们先规划一个项目结构。这个结构不是必须的但合理的目录组织可以让脚本更易于维护。video-downloader/ ├── downloader.py # 核心下载脚本 ├── batch_urls.txt # 批量下载的链接列表 ├── output/ # 视频输出目录 │ ├── videos/ │ └── logs/ └── config.ini # 可选配置文件在后面的实战部分我们会逐步实现这个项目中的核心脚本。3. 核心命令与参数拆解3.1 基础下载命令先用最简单的命令测试工具是否正常工作。例如下载一个公开视频yt-dlp https://www.example.com/watch/12345命令执行后yt-dlp 会解析页面内容找到视频流并下载到当前目录。默认情况下它会自动选择可用的最佳画质。不过这里有一个需要理解的点很多网站的“最佳画质”是音视频分离的两个流yt-dlp 需要调用 FFmpeg 合并所以要确保 FFmpeg 已安装。3.2 列出所有可用格式在正式下载之前通常先用-F参数查看页面提供的所有媒体流yt-dlp -F URL输出内容会列出每一个格式的编号、扩展名、分辨率、码率等信息。比如类似下面这样ID EXT RESOLUTION FORMAT INFO 18 mp4 640x360 1440K mp4, avc1.42001E, 30fps, video only 22 mp4 1280x720 2780K mp4, avc1.64001F, 30fps, video only 140 m4a audio only m4a, mp4a.40.2, 128K, audio only这个信息非常关键因为不同网站的编码方案差异很大。有些视频流可能是webm格式有些可能是m4a音频流。通过-F查看以后你就能清楚地知道当前页面提供了哪些可下载的资源。3.3 选择指定清晰度并合并当视频和音频分离时可以组合选择。例如yt-dlp -f bv[height1080]ba/b[height1080] --merge-output-format mp4 URL参数解释bv表示 best video即最佳视频流[height1080]表示限制高度不超过 1080ba表示 best audio即最佳音频流表示将视频流和音频流合并最后面的b[height1080]是兜底方案如果上面组合失败就选一个包含音视频的较佳整体文件--merge-output-format mp4指定合并后的输出格式为 MP4。这个组合方式在实际项目中非常常用它能保证下载的视频不超过 1080p并且不会出现“有画无声”的情况。3.4 指定输出目录与文件名模板默认输出文件名不够清晰建议使用-o参数自定义模板yt-dlp -o %(title)s.%(ext)s URL更规范的模板可以包含上传者、日期、清晰度等信息yt-dlp -o output/videos/%(uploader)s/%(date)s_%(title)s_%(height)sp.%(ext)s URL这里的%(字段名)s是由 yt-dlp 提供的输出模板变量支持的字段包括title、uploader、id、upload_date、height、ext等。这些变量可以在脚本中组合使用让下载文件归档到合理的目录结构里。3.5 下载字幕与缩略图如果视频包含字幕可以加上--write-subs --write-auto-subs参数。--write-subs写入普通字幕--write-auto-subs写入自动生成字幕。还可以用--sub-langs指定字幕语言。缩略图则通过--write-thumbnail参数下载。yt-dlp --write-subs --write-auto-subs --sub-langs zh-Hans,en --write-thumbnail URL字幕文件默认与视频同名但扩展名不同例如.vtt或.srt。如果你希望把字幕嵌入视频文件则需要使用 FFmpeg 相关参数但那属于更进阶的用法本文先不展开。3.6 限速与断点续传下载大文件时如果担心占用带宽可以限制速度yt-dlp --limit-rate 2M URL--limit-rate的单位可以是K、M等。yt-dlp 默认支持断点续传如果下载中断重新执行同样的命令它往往能从断点处继续不需要额外参数。对于不完整的文件也可以使用--continue强制开启续传但多数情况下默认行为已经足够好。3.7 批量下载与播放列表如果有多个链接可以创建一个文本文件把链接逐行写入然后使用-a参数批量下载yt-dlp -a batch_urls.txt批量模式下稍加扩展就能做到逐个下载并记录日志。对于支持播放列表的网站urllib 或 yt-dlp 会自动识别播放列表中的所有视频默认会全部下载。如果只想下载最近几个可以用--playlist-items 1-5限制范围。--playlist-end 10则可以限制最多下载 10 个视频。4. 完整实战案例用 Python 封装一个“视频下载神器”4.1 需求分析直接使用命令行已经能满足大部分需求但为了长期使用我们还需要解决几个问题链接多的时候手动输入命令太麻烦下载失败需要自动重试日志需要持久化方便排查问题输出目录需要按日期和来源自动整理最好支持从配置文件读取参数而不是每次修改命令。基于这些需求我们编写一个 Python 脚本把 yt-dlp 封装成可复用的下载工具。脚本主要包含四个模块参数解析、链接读取、下载执行、日志记录。4.2 创建项目结构在本地新建目录video-downloader按下面的结构创建文件video-downloader/ ├── downloader.py # 主脚本 ├── batch_urls.txt # 批量链接 ├── output/ │ ├── videos/ │ └── logs/在output目录下创建videos和logs两个子目录用于存放视频文件与日志文件。4.3 核心代码实现我们先实现downloader.py。这个脚本的功能包括读取命令行传入的单个链接或者批量文件调用 yt-dlp 下载视频对下载结果进行简单重试生成带时间戳的日志文件。# 文件路径video-downloader/downloader.py import argparse import logging import subprocess import sys import time from pathlib import Path BASE_DIR Path(__file__).resolve().parent VIDEO_DIR BASE_DIR / output / videos LOG_DIR BASE_DIR / output / logs VIDEO_DIR.mkdir(parentsTrue, exist_okTrue) LOG_DIR.mkdir(parentsTrue, exist_okTrue) logging.basicConfig( levellogging.INFO, format%(asctime)s [%(levelname)s] %(message)s, handlers[ logging.StreamHandler(sys.stdout), logging.FileHandler(LOG_DIR / fdownload-{time.strftime(%Y%m%d-%H%M%S)}.log, encodingutf-8) ] ) logger logging.getLogger(video-downloader) def read_urls_from_file(file_path: Path) - list[str]: 从文本文件逐行读取链接忽略空行和注释行。 if not file_path.exists(): logger.error(链接文件不存在: %s, file_path) return [] urls [] for line in file_path.read_text(encodingutf-8).splitlines(): line line.strip() if not line or line.startswith(#): continue urls.append(line) logger.info(从文件读取到 %d 个链接, len(urls)) return urls def download_video(url: str, output_dir: Path, max_retry: int 3) - bool: 使用 yt-dlp 下载单个视频并支持失败重试。 参数说明: url: 视频页面地址 output_dir: 视频输出目录 max_retry: 最大重试次数 返回: bool 表示是否下载成功 cmd [ yt-dlp, --newline, -f, bv[height1080]ba/b[height1080], --merge-output-format, mp4, -o, str(output_dir / %(uploader)s/%(date)s_%(title)s_%(height)sp.%(ext)s), --write-subs, --write-auto-subs, --sub-langs, zh-Hans,en, --limit-rate, 8M, url ] for attempt in range(1, max_retry 1): logger.info(开始下载: %s (第 %d 次尝试), url, attempt) result subprocess.run(cmd, textTrue, encodingutf-8, errorsreplace) if result.returncode 0: logger.info(下载成功: %s, url) return True logger.warning(下载失败准备重试: %s, url) time.sleep(attempt * 2) logger.error(多次重试后仍然失败: %s, url) return False def main(): parser argparse.ArgumentParser(description基于 yt-dlp 的批量视频下载工具) group parser.add_mutually_exclusive_group(requiredTrue) group.add_argument(-u, --url, help单个视频链接) group.add_argument(-f, --file, help批量链接文件路径默认读取 batch_urls.txt) args parser.parse_args() if args.url: urls [args.url] else: file_path Path(args.file) if args.file else BASE_DIR / batch_urls.txt urls read_urls_from_file(file_path) if not urls: logger.error(没有可下载的链接程序退出) sys.exit(1) success_count 0 for i, url in enumerate(urls, start1): logger.info(进度: %d/%d, i, len(urls)) if download_video(url, VIDEO_DIR): success_count 1 logger.info(全部处理完成成功 %d 个失败 %d 个, success_count, len(urls) - success_count) if __name__ __main__: main()4.4 代码要点说明脚本中有几处值得注意的设计使用subprocess.run调用系统命令而不是通过 Python 的 SDK 初始化方式可以避免依赖 API 版本变化--newline参数让 yt-dlp 在下载过程中输出实时进度方便在日志里看到进度输出模板中包含%(uploader)s这样不同来源的视频会自动按上传者分目录重试策略采用递增等待时间避免失败后立即重试导致被网站限流日志同时输出到控制台和文件文件日志会带上时间戳方便追溯历史下载记录。4.5 配置化改进把常用参数放到配置文件中更便于维护。这里不引入复杂的配置库直接用 Python 内置的configparser来读取一个简单的config.ini文件。; 文件路径video-downloader/config.ini [download] format bv[height1080]ba/b[height1080] merge_format mp4 output_template output/videos/%(uploader)s/%(date)s_%(title)s_%(height)sp.%(ext)s limit_rate 8M write_subs true sub_langs zh-Hans,en然后在downloader.py中增加读取配置的逻辑。核心思路是默认参数从配置文件读取命令行参数优先级更高。由于篇幅原因这里只展示配置读取的关键片段# 文件路径video-downloader/downloader.py配置读取片段 import configparser def load_config() - configparser.ConfigParser: config configparser.ConfigParser() config_path BASE_DIR / config.ini if config_path.exists(): config.read(config_path, encodingutf-8) return config这样日常使用中只需要维护config.ini和batch_urls.txt不需要频繁修改脚本文件。4.6 运行与验证首先创建一个batch_urls.txt每行一个链接# 这是示例链接请替换成你有权限下载的视频地址 https://www.example.com/media/001 https://www.example.com/media/002然后在项目根目录执行python downloader.py -f batch_urls.txt或者只下载单个链接python downloader.py -u https://www.example.com/media/001程序运行后控制台会输出类似下面的日志2025-01-15 14:30:00,123 [INFO] 从文件读取到 2 个链接 2025-01-15 14:30:00,124 [INFO] 进度: 1/2 2025-01-15 14:30:00,125 [INFO] 开始下载: https://www.example.com/media/001 (第 1 次尝试) 2025-01-15 14:30:26,880 [INFO] 下载成功: https://www.example.com/media/001下载完成后进入output/videos目录可以看到按上传者/日期命名的视频文件。日志文件则保存在output/logs下。5. 常见问题与排查思路用 yt-dlp 搭建下载工具的过程中新手最容易卡在几个固定的报错上。这里整理一份实用的排查表。问题现象常见原因解决思路提示yt-dlp 不是内部或外部命令Python Scripts 目录未加入 PATH或安装后未重启终端重新打开终端或找到 Scripts 路径加入环境变量下载后视频没有声音视频流和音频流分离但 FFmpeg 缺失安装 FFmpeg并确认ffmpeg -version可用报错HTTP Error 403网站要求登录或做了访问限制使用--cookies-from-browser chrome读取浏览器登录态报错Unsupported URL链接格式不被支持或 yt-dlp 版本太旧检查链接是否为公开可访问页面并升级 yt-dlp下载速度很慢服务端限制单连接速度或网络链路质量不稳定使用--limit-rate降低预期或适当提高分段并发数文件下载到一半失败网络中断、服务器断开连接、磁盘空间不足检查磁盘空间利用默认断点续传重新执行命令合并 MP4 失败FFmpeg 版本过旧或格式不支持直接封装升级 FFmpeg尝试改用mkv格式5.1 输出日志只有标题没有进度条如果脚本中使用了--newline正常情况下会有逐行进度输出。如果看不到很可能是 yt-dlp 检测到非终端环境自动关闭了进度显示。这时不要慌程序仍然在正常工作只是没有可视化进度。可以在日志中记录开始和结束时间用来判断任务是否完成。5.2 下载 1080p 视频时视频和音频不同步多数情况下yt-dlp 合并后的音视频是同步的。如果出现不同步常见原因是编码参数差异过大或者视频流与音频流来自不同的编码器。可以先尝试升级 FFmpeg因为新版 FFmpeg 对时间戳处理更完善。如果问题依旧可以尝试下载整体文件中质量较高的单一文件格式也就是使用-f b[height1080]避免音视频合并流程。5.3 如何获取需要登录的视频如果视频需要登录后才可访问yt-dlp 提供了从浏览器读取 Cookie 的方式。最常用的是yt-dlp --cookies-from-browser chrome URL这里要注意浏览器必须处于未彻底退出登录的状态因为 yt-dlp 会读取浏览器本地的 Cookie 数据库。使用该功能时请确保你有权访问目标视频且操作符合网站的服务条款。对敏感账号信息建议在专用的测试浏览器环境中操作避免引发安全问题。5.4 输出文件名为乱码或包含不合法字符Windows 文件名不支持/、\、:、*、?、、、、|等字符。yt-dlp 的sanitize_filename函数会自动清理大部分不合法字符。如果仍遇到问题建议在输出模板中加入视频id字段例如-o %(id)s_%(title)s.%(ext)s或者直接在 Python 脚本中二次处理文件名把不合法字符替换掉。6. 最佳实践与工程建议6.1 把下载器设计成幂等任务在工程实践中下载脚本最好具备幂等性。也就是说同一个链接无论执行多少次结果都应该一致。通过固定的输出模板和文件名包含视频 id可以避免重复下载时生成多个副本。虽然 yt-dlp 检测到文件存在时会跳过但增加 id 会更精确因为不同页面上的标题可能完全一样。6.2 日志分级与日志持久化日志不要只打在控制台最好同时写入文件。建议按日期切分日志保留最近 7 到 30 天的日志文件。日志级别上INFO 记录下载 URL 和成功失败状态WARNING 记录重试和异常ERROR 记录最终失败。这样定位问题时能快速从大文件中找到有效信息。6.3 重试策略与退避网络下载的不确定性很高失败重试是必须的。但重试不能太频繁建议采用指数退避策略第一次失败后等 2 秒第二次等 4 秒第三次等 8 秒最多重试 3 到 5 次。如果仍然失败就把链接写入失败队列供后续人工处理。6.4 磁盘空间与文件清理视频文件通常很大连续批量下载前要检查磁盘剩余空间。可以在脚本中增加磁盘检查逻辑当剩余空间低于阈值时停止任务。另外建议定期把下载完成且确认无误的文件移动到长期存储设备保持下载目录可控。6.5 定时任务与无人值守在 Linux 或 macOS 上可以通过crontab设置定时任务比如每天凌晨 3 点执行一次下载脚本。Windows 上可以使用任务计划程序。定时任务场景下需要特别注意日志和错误通知。建议脚本在任务结束时生成退出码如果连续失败可以通过邮件、企业微信或钉钉机器人推送提醒。6.6 安全与权限最小化下载工具可能需要读取浏览器 Cookie这会涉及到账号凭证。建议在专用机器上运行而不是随意在公共电脑上使用。如果脚本会在服务器上运行给脚本创建一个专属系统用户不要使用 root 或管理员账号。配置文件中的敏感信息要设置严格的文件权限避免被其他用户读取。7. 总结与学习路线通过本文的实践你应该已经掌握了一条完整的视频下载工具链安装 Python、yt-dlp 和 FFmpeg理解 yt-dlp 常用的-F、-f、-o、--merge-output-format等参数然后用 Python 封装了支持批量、日志、重试的下载脚本。这套工具从功能上已经算得上一个合格的“视频下载神器”。接下来可以继续学习的方向包括使用 yt-dlp 的 Python API 替代 subprocess 调用实现对下载进度的更精细控制增加定时任务和失败通知构建完整的无人值守下载系统结合 FFmpeg 做视频后处理比如转码、截图、拼接、提取音频设计 Web 管理界面通过网页提交下载任务适合团队内部使用研究不同站点媒体流的编码格式差异更好地理解 HLS、DASH 等流媒体协议。在实际项目中优先关注三点一是始终升级 yt-dlp因为网站页面结构经常变化二是保证 FFmpeg 环境稳定否则合并不了音视频三是做好日志和磁盘空间管理避免长时间运行后磁盘被占满。视频下载工具本身并不复杂但把它做成稳定、可维护、自动化的小系统则需要工程化思维。如果你动手把脚本跑起来并尝试改造成自己需要的版本相信很快就能体会到命令行工具的乐趣。