yt-dlp：20 万星的命令行音视频下载器

你有没有遇到过这种窘境：想把某个在线视频留一份本地副本，网页右键"另存为"得到的却是一个几百 KB 的 .m3u8 索引文件？或者明明浏览器里能播，某个下载工具却提示"暂不支持该站点"？这类问题在命令行世界里有一个几乎人尽皆知的答案——yt-dlp。它不靠图形界面取胜，靠的是持续更新的站点适配能力和极其细粒度的参数控制。

项目名片

它解决什么问题

在线视频的分发方式极其碎片化：不同站点用不同的加密、不同的分片格式、不同的清晰度标注。yt-dlp 的核心价值是把这层差异抹平——你只需要给它一个 URL，它负责解析出真实的媒体流地址，再按你指定的格式、清晰度、文件命名规则下载到本地。官方 README 强调它支持"数千个站点"，并提供了 supportedsites.md 列表供查询。

核心机制

从 README 的目录结构就能看出它的设计思路：解析与下载分离，一切皆可配置。

• 格式选择（FORMAT SELECTION）：支持按格式过滤、排序，可以精确指定"优先 1080p、否则取最高可用"这类策略。
• 输出模板（OUTPUT TEMPLATE）：文件名不是固定的，而是用模板变量拼出来，方便批量归档。
• 元数据修改（MODIFYING METADATA）：下载后还能改写元数据。
• 后处理（Post-processing）与 SponsorBlock 选项：下载不是终点，还能做后续加工，甚至按 SponsorBlock 数据处理片段时间轴。
• 插件系统与嵌入能力：既能装第三方插件扩展功能，也能把 yt-dlp 作为 Python 库嵌进自己的程序。
• 鉴权与网络绕行：支持账号登录、netrc 认证、代理等网络选项，以及针对地区限制（Geo-restriction）的专门选项。

安装与最小使用

README 给出三种安装途径：官方二进制、pip、或第三方包管理器。各平台推荐文件如下：

# Linux/BSD（平台无关的 zipimport 二进制，需要 Python 环境）
# 下载 yt-dlp 后
chmod +x yt-dlp

# 或直接用 pip 安装
pip install -U yt-dlp

最小使用示例：

# 最简单：直接下载
yt-dlp "https://example.com/watch?v=xxxx"

# 预演模式：只看会下载什么，不动手
yt-dlp -s "https://example.com/watch?v=xxxx"

# 指定输出模板
yt-dlp -o "%(title)s.%(ext)s" "https://example.com/watch?v=xxxx"

# 只取音频并转码
yt-dlp -x --audio-format m4a "https://example.com/watch?v=xxxx"

适合谁用与什么时候别用

适合：需要批量归档内容的研究者、播客听众、课程学习者；想把 yt-dlp 集成进自动化流水线的开发者（README 专设"EMBEDDING YT-DLP"章节）；对文件命名和格式有严格要求的整理癖。

别用：你需要的是"点一下就完事"的图形界面体验（yt-dlp 本质是 CLI，虽有第三方 GUI 包装）；你的需求是实时在线播放而非落盘；或者你所在场景不允许下载内容——技术能力不等于使用许可，站点的服务条款和版权归属仍需自行判断。

三条真实的坑

1. 站点适配是"打地鼠"游戏。项目 README 单列了 Update 章节，正因为站点改版频繁，老版本经常解析失败。装完不升级，大概率过几周就报错。 2. Linux/BSD 的推荐二进制依赖 Python。如果你的服务器是精简镜像，没装 Python 就跑不起来 zipimport 版本，需自行补齐运行环境。 3. 功能多意味着参数陡峭。README 的选项分为通用、网络、地区限制、视频选择、下载、文件系统、缩略图、字幕、鉴权、后处理、SponsorBlock、提取器参数等十几组，还有配置文件、环境变量、预设别名三套机制。新手照抄一段别人的长命令，出问题时很难定位是哪个参数在起作用。建议先用 -s 模拟跑一遍。

小结

yt-dlp 之所以能积累 20 万星，不在于它解决了某个新问题，而在于它把"从网页取回媒体文件"这件老事做到了极致的工程化：格式可筛、命名可模板化、元数据可改、可装插件、可作为库嵌入。它是一把相当锋利的瑞士军刀——前提是你会读说明书，并且尊重内容的版权边界。

参考资料

• yt-dlp 仓库：https://github.com/yt-dlp/yt-dlp
• 支持站点列表：仓库内 supportedsites.md
• 安装详解 Wiki：https://github.com/yt-dlp/yt-dlp/wiki/Installation
• FAQ：https://github.com/yt-dlp/yt-dlp/wiki/FAQ
• 前身项目 youtube-dl：https://github.com/ytdl-org/youtube-dl