Yt-dlp 入门笔记 & 不简明教程

这篇笔记整理了 yt-dlp 的安装与常用下载命令，包括下载 MP4 视频、提取 MP3 音频、批量下载播放列表，以及使用 Cookie 和代理。想直接使用，可以先看安装后的命令速查；想了解画质选择，以及视频编码和封装格式的区别，再往下看详细说明。

太长不看： 推荐把这篇教程和想下载的音视频网址一起发给 AI，说明需要视频还是音频、期望的格式和画质，让它参考文中的命令帮你下载。

安装 Yt-dlp#

依赖确认

确认系统已正确安装 FFmpeg 和随附的 ffprobe；合并视频与音频、转换 MP3 都会用到它们。

ffmpeg -version
ffprobe -version

下载 YouTube 视频还需要留意 JavaScript 依赖：当前版本使用 yt-dlp-ejs 和受支持的 JavaScript 运行时完成挑战解析，官方推荐 Deno。不同安装渠道是否附带 EJS 不尽相同，缺失时按官方 EJS 安装说明补齐。

官方安装说明：https://github.com/yt-dlp/yt-dlp/wiki/Installation，以下列出个人常用系统的安装升级命令

MacOS 系统

brew install yt-dlp ffmpeg deno

# 更新
brew upgrade yt-dlp ffmpeg deno

Ubuntu 系统

sudo add-apt-repository ppa:tomtomtom/yt-dlp
sudo apt update
sudo apt install yt-dlp ffmpeg

# 更新
sudo apt update
sudo apt install yt-dlp ffmpeg

上面是通过第三方 PPA 安装的方式，版本更新取决于维护者；Deno 和 EJS 仍需按前面的官方说明确认。包管理器版本过旧时，参考官方安装说明选择其他渠道，不要混用不同渠道的更新命令。

安装后查询 yt-dlp 版本

yt-dlp --version

后面的截图保留自 2024 年，原示例使用 yt-dlp 2024.08.01，仅用于解释输出和格式选择，不代表当前版本的下载结果。实际可用画质、格式 ID 和网站限制可能变化，请以本机查询结果为准。

常用命令速查#

以下命令以已安装依赖为前提。将 "视频网址" 或 "播放列表网址" 替换为实际链接，保留两侧引号，避免网址中的 &、? 等字符被 shell 误处理。没有指定保存路径时，文件默认下载到当前目录。

# 默认下载视频
yt-dlp "视频网址"

# 优先选择 MP4 视频和 M4A 音频，没有时回退到其他格式
yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/bv*+ba/b" "视频网址"

# 提取并转换为 MP3 音频
yt-dlp -x --audio-format mp3 "视频网址"

# 下载播放列表；再次使用同一记录文件时跳过已下载项目
yt-dlp --download-archive archive.txt "播放列表网址"

MP4 优先不等于保证输出 MP4，也不保证所有播放器都支持其中的编码。需要精细选择画质、添加封面或使用登录状态时，继续看下面的说明。

默认下载命令#

在已安装 FFmpeg、正常下载到文件且未用配置文件覆盖选项时，默认的格式选择通常为 -f "bv*+ba/b"，意为选择最佳的视频音频组合，后文会解释它的含义。

yt-dlp "https://www.youtube.com/watch?v=60ItHLz5WEA"

后续命令中的 "视频网址" 都需要替换成实际链接；格式 ID 则需要先用 --list-formats 查询，不能照搬旧截图中的编号。

通过截图中 yt-dlp 输出的信息，我们得知：

它分别下载了视频流文件和音频流文件，最终合并为 Alan Walker - Faded [60ItHLZ5WEA] webm 视频文件

616 Alan Walker - Faded [60ItHLz5WEA]. f616.mp4 视频文件（Video Only） 251 Alan Walker - Faded [60ItHLz5WEA].f251.webm 音频文件

这里值得留意的是 616 和 251，它们是资源 ID，稍后会查看这个视频下的所有资源

查看可供下载的资源列表#

yt-dlp --list-formats "视频网址"

截图中展示了这个视频可获取的全部资源 —— 不同的封装格式、分辨率、编码、码率等

这里选取 720P 分辨率的视频资源进行说明

简要来说第一列为资源ID、第二列是容器后缀、第三列是画面分辨率

第六列的 “345K”、“808K” 是视频的码率。同样的编码和相近参数下，码率可以作为质量的参考，但不同编码的压缩效率不同，不能只凭码率判断哪个画质最好。

第七列展示传输协议，例如 https、m3u8；m3u8 通常对应 HLS，另外还有 MPEG-DASH 等流媒体技术。这里先把它们理解为传输方式，不必仅为了画质选择某一种协议。

第八列的 av01.0.05M.08、avc1.4D401F、vp09.00.40.08 描述了编码格式，分别对应 AV1、H.264、VP9（AV1 最新、VP9 是 Google 的开放标准，更适合4K等资源编码、H.264 使用最为广泛）

这里要区分编码格式和容器封装格式：前者 AV1、H.264、VP9 是编码格式，而我们下载到的视频 MP4、MKV、WEBM、AVI 是容器封装格式，容器将视频流、音频流、字幕等“打包”到一个文件中。实际使用 yt-dlp 时一般不需要指定具体资源，后面有更易用的命令。

第十列的 “video only” 说明这个资源只包含视频画面，不包含声音。完整截图中的 18 号资源则同时包含音视频；具体编码应以对应行的 VCODEC、ACODEC 列为准。

了解了以上信息，我们可以手动指定下载 398 AV1 编码 720P 分辨率的视频和 140 MP4A 编码的音频作为测试

# mp4
yt-dlp -f "398+140" "视频网址"

下载后的文件为 mp4 格式，这是 yt-dlp 自动判断的，如果指定 247 的 VP9 编码，则下载合并后是 mkv 格式，同时也把音频换为 251 的 opus 编码，则会自动合并为 webm 格式，yt-dlp 会选择适宜的容器封装技术来存储视频、音频流

# mkv
yt-dlp -f "247+140" "视频网址"

# webm
yt-dlp -f "247+251" "视频网址"

如需在合并音视频流时指定 MP4 容器，可使用 --merge-output-format 参数。它只影响需要合并的情况，不会把视频编码自动转成 H.264，也不会转换无需合并的单文件下载。

# mp4
yt-dlp -f "247+251" --merge-output-format mp4 "视频网址"

常用命令整理#

优先下载 MP4 视频

优先选择 MP4 视频和 M4A 音频，如果没有，则回退到其他格式；这不是强制转码为 MP4。

yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/bv*+ba/b" "视频网址"

不关心最终格式，获取「最佳视频流」和「最佳音频流」，合并为一个视频

yt-dlp -f "bv+ba/b" "视频网址"

优先下载指定分辨率的视频（720P、1080P、4K）

下面的 height=720 等条件是精确匹配视频高度，并限定 MP4/M4A 资源；找不到对应组合时，/b 会回退到同时包含音视频的最佳单一资源，且没有分辨率限制。因此它不是“最高 720P / 1080P / 4K”的上限设置，也不保证最终下载到指定分辨率。

# 720P
yt-dlp -f "bv[height=720][ext=mp4]+ba[ext=m4a]/b" "视频网址"

# 1080P
yt-dlp -f "bv[height=1080][ext=mp4]+ba[ext=m4a]/b" "视频网址"

# 4K
yt-dlp -f "bv[height=2160][ext=mp4]+ba[ext=m4a]/b" "视频网址"

下载 MP3 格式的音频

# 提取 MP3，并将缩略图嵌入为封面
yt-dlp --extract-audio --embed-thumbnail --audio-format mp3 "视频网址"

# 不添加封面
yt-dlp --extract-audio --audio-format mp3 "视频网址"

"--extract-audio" 参数从资源中解析出音频流

"--embed-thumbnail" 设置文件封面缩略图

"--audio-format" 保存的音频格式，可选值为 best (default), aac, alac, flac, m4a, mp3, opus, vorbis, wav

补充：这里的 --audio-format 参数，如果你指定了 mp3、flac、opus, 最终的文件也会是对应名称的后缀文件、如果指定了 aac，最终保存的文件是 .m4a 文件，指定了 vorbis 则文件后缀为 .ogg，跟视频同理，yt-dlp 会根据你选择的音频编码选择适合的容器进行存储

下载 Playlist 视频列表

yt-dlp --download-archive archive.txt "https://www.youtube.com/playlist?list=PLSk-fsG1YwI9Zu4e8MJBKM2TRjWcXqCDw"

--download-archive archive.txt 将成功下载的项目 ID 存入记录文件。下次使用同一文件时跳过这些项目；换了工作目录时，要注意是否仍然指向原来的 archive.txt。

更多的 -f 参数说明，参考 yt-dlp 官方文档：format-selection-examples

格式参数的补充说明#

参数 -f "bv*+ba/b" 更详细的介绍

在前面说明的常规下载条件下，默认的 "bv*+ba/b" 是 "bestvideo*+bestaudio/best" 的简写。

bv* 选择包含视频的最佳资源，允许它同时带有音频；bv 则只选择纯视频资源。默认组合在选中资源已带音频时通常不再添加额外音轨，否则再与 ba 选择的最佳音频合并。

“+” 加号代表单一视频和单一音频下载后合并为一个音视频文件，斜线 “/” 表示 “或”，当前方条件不满足时使用后面的条件进行匹配

best 表示获取包含音频流的最佳视频，如果仅指定 -f b，那么如果仅有一个 360P 的同时包含视频和音频的视频资源，也会被下载，虽然它跟通常意义上的 “高清” 不沾边儿，通常作为一个 “保底” 的可选参数

参数 -f "bv+ba" --merge-output-format mp4 和 -f "bv[ext=mp4]+ba[ext=m4a]" 的选择与使用

初看感觉这两个命令差不多 —— 都能下载 MP4 格式的视频，但还是有一些本质区别

前者的意思是分别获取「最佳视频流」和「最佳音频流」合并为 MP4 格式的视频，后者是在选择资源的时候就从 MP4 视频流及 M4A 音频流中下载其中的最佳画质，最终合并的也是天然的 MP4 视频格式

如果只想优先选择 MP4/M4A 资源，可以使用后者；它选的是符合这些条件的最佳资源，不一定是所有格式中的最高画质。MP4 容器内部仍可能是 AV1、VP9 等编码，文件后缀本身不能保证播放器兼容性。

--merge-output-format mp4 只指定合并容器，不会转换编码。更在意老设备兼容性时，需要进一步确认视频、音频编码是否受设备支持，常见组合是 H.264 视频与 AAC 音频；不关心容器时，则无需强制指定 MP4。

我最开始碰见需要设置 Cookie 的场景是下载 Bilibili 视频时，不登录下载到的视频画质低（是的，除了 Youtube，yt-dlp 也支持包括 Bilibili 在内的很多网站）

其中一个可行的方式是导出 Cookie，Firefox Cookies Text 插件：https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/

yt-dlp --cookies cookies.txt "https://www.bilibili.com/video/BV1H44y1w7AX"

Cookie 文件需要是 Netscape 格式。YouTube 等网站也可以使用 --cookies，但登录状态不能保证绕过所有访问限制，下载失败时仍需结合具体报错判断。

在自己的电脑上，也可以直接读取已登录浏览器的 Cookie，省去手工导出：

# 使用本机 Firefox 的登录状态
yt-dlp --cookies-from-browser firefox "视频网址"

# 使用 Chrome 时将浏览器名称改为 chrome
yt-dlp --cookies-from-browser chrome "视频网址"

浏览器配置、系统权限和 Cookie 加密方式都会影响读取结果；遇到数据库占用时可先关闭浏览器再试，其他错误参考官方 Cookie 说明。这些示例说明的是参数用法，不代表已在所有系统和浏览器上实测。

Cookie 属于敏感登录凭据，不要上传给 AI、提交到代码仓库或分享给他人；只在受信任的本机环境中使用。

使用 Socks5 设置代理#

最后，不得不提的 --proxy 参数使用如下，预祝网络畅通，心舒畅 🌈

yt-dlp --proxy "socks5://127.0.0.1:10808" "视频网址"

将示例地址和端口替换为本机实际运行的代理地址；这个参数不会自动启动代理服务。

了解至此，对于 yt-dlp 的简单实用场景，就基本能应付的来，更多的参数信息参考 --help 命令或 Document