一键下载，视频音频全搞定 | yt-dlp

📌 项目地址：yt-dlp/yt-dlp | ⭐ 164,899 颗星 | 🔧 Python | 📜 未标注

为什么我弃用youtube-dl换成了yt-dlp

这个项目有164899颗星，是youtube-dl最活跃的分支。我用了三年多，有两点最直观的感受：第一，它修复网站结构变化的速度比原版快，经常是某站改版后两天内就能更新支持；第二，它默认的行为更合理——比如自动合并音视频流、优先使用更高效的编码（avc1优于vp9）。这两点直接减少了我的脑力消耗。

格式选择：不是“最好”，而是“最合适”

很多视频站会把视频轨和音频轨分开。yt-dlp用 -f 参数让你指定要哪个视频流、哪个音频流，然后自动用FFmpeg合并。

最简单的用法：下载最佳视频轨和最佳音频轨，然后合并：

yt-dlp -f "bv+ba" URL

bv 是best video，ba是best audio。这行命令等价于“给我最高质量”，但合并后体积可能大。如果你想限制编码或分辨率：

yt-dlp -f "bv[height<=1080][vcodec^=avc1]+ba" URL

filter属性包括：分辨率（height/width）、帧率（fps）、编码名、视频码率等。比如只下载视频时宽小于高的竖屏视频：

yt-dlp -f "bv[width<=height]+ba" URL

如果你手上有FFmpeg，还可以用 --merge-output-format mkv 强制合并成Matroska容器（有些直播站需要）。

注意：filter写法是 [属性名=值] 或 [属性名<=值] 等关系符，多个filter用逗号或空格分隔？README里写的是用[height=1080]。这里的语法在README的“Filtering Formats”小节有完整说明。

输出模板：文件命名就是你自己的数据库

默认输出是 %(title)s.%(ext)s，但yt-dlp提供了几十个变量。我自己的配置是：

yt-dlp -o "%(upload_date)s - %(title)s [%(id)s].%(ext)s" URL

上传日期格式是YYYYMMDD，这样按文件名排序就能按时间序。如果是播放列表，可以用：

yt-dlp -o "%(playlist_title)s/%(playlist_index)03d - %(title)s.%(ext)s" URL

自动创建播放列表名的子文件夹，索引补零到3位。变量列表很长，包括 duration、resolution、view_count、channel 等，在README的“OUTPUT TEMPLATE”章节。

后处理：下载完自动干活

FFmpeg装好之后，yt-dlp可以自动化很多事情。

转成MP3并嵌入封面：

yt-dlp -x --audio-format mp3 --embed-thumbnail URL

-x 表示提取音频（extract audio），--embed-thumbnail 把视频的缩略图塞进MP3作为封面。

SponsorBlock集成是这项目独有的。它会识别视频里的赞助、片头、片尾、自推等片段，下载时直接跳过：

yt-dlp --sponsorblock-remove all URL

你也可以只删赞助和片头：

yt-dlp --sponsorblock-remove sponsor,intro URL

类别列表在“SponsorBlock Options”小节里：sponsor, intro, outro, selfpromo, preview, filler, interaction_reminder, music_offtopic。我一般只删赞助和片头。

嵌入外挂字幕也很方便：

yt-dlp --write-subs --embed-subs --sub-langs en URL

如果视频有多语言字幕，–sub-langs可以指定只下英文。

配置文件和插件：固定套路别再重复敲

每次敲一长串参数烦人。yt-dlp支持配置文件，位置是 ~/.config/yt-dlp/config（Linux/macOS）或 %APPDATA%yt-dlpconfig.txt（Windows）。我自己的配置：

-f bv+ba
-o ~/Videos/%(upload_date)s - %(title)s.%(ext)s
--embed-thumbnail
--embed-subs
--sub-langs en
--sponsorblock-remove sponsor,intro

之后只需 yt-dlp URL，所有选项自动生效。配置文件支持多行，注释以#开头。

如果某个网站yt-dlp原生不支持，可以去插件市场找。插件是Python包，通过 pip 安装后自动加载。开发插件需要实现一个 class InfoExtractor，具体看README的“PLUGINS”章节。

和youtube-dl的具体差异

我迁移时踩了几个坑，列出来：

• 格式选择策略：youtube-dl默认 -f best 可能只下载一个流（如果视频只有单一文件），而yt-dlp的默认行为是下载最佳视频+最佳音频并合并。-f bv+ba 在yt-dlp里是推荐写法，而在youtube-dl里不保证效果。
• 更新频率：yt-dlp基本上每月都有新release，而youtube-dl有时半年才更一次。这导致很多网站换了API后youtube-dl就歇菜，而yt-dlp很快跟上。
• 弃用参数：--prefer-ffmpeg 在yt-dlp里已无意义，因为现在默认就用FFmpeg。--audio-quality 的参数格式也变了（现在是0-10的浮点数，默认0最好）。
• Python版本：yt-dlp需要Python 3.7+，youtube-dl支持2.7。
• SponsorBlock：这是yt-dlp独有的，youtube-dl没有。
• 插件系统：yt-dlp支持动态加载插件，youtube-dl只能写死扩展。

入门三步

1. 安装 pip install yt-dlp，或者从GitHub Release下载单文件可执行文件（自带Python环境，不用装Python）。
2. 装FFmpeg。不装的话你只能下载单一封装的文件（比如YouTube上常见的M4A纯音频），不能合并音视频、不能转格式、不能嵌入字幕。在macOS上是 brew install ffmpeg，Linux用包管理器，Windows下载二进制并放到PATH。
3. 跑一次测试：yt-dlp --version 确认安装，然后 yt-dlp -f "bv+ba" "https://www.youtube.com/watch?v=dQw4w9WgXcQ" 下载一个最普通的视频。

完整命令列表看README里的“USAGE AND OPTIONS”大章节。支持的站点名单在 supportedsites.md（项目根目录）。遇到问题可以进Discord群（README顶部有链接）。

我觉得yt-dlp最大的价值就是把所有选择权都开放给你，但又不强求——默认行为已经很好用。你只需要在最需要定制的地方写几句参数，剩下的交给它自己判断。