yt-dlp 归档视频踩坑：格式串、ffmpeg、和两种 cookie 不是一回事

有几门公开课的录像我想存到本地，怕哪天原站下架。用 yt-dlp 试了一下，本以为一行命令的事，结果前后卡了大半天。下面四类问题，按我踩到的顺序写。

一、默认下下来画质很低，还以为工具不行

第一次直接跑：

yt-dlp <视频地址>

下完一看，糊得没法看。以为是工具默认不给高画质，其实是它的默认策略问题：很多站点的高画质视频流和音频流是分开的，yt-dlp 默认挑一个「音视频合在一起」的格式，而合并格式通常只有低分辨率。高分辨率的那一档往往只有画面、没有声音。

先看这个视频到底有哪些格式：

yt-dlp -F <视频地址>

输出是一张表，每行有 format code、扩展名、分辨率、码率、编码。表里能看到有些行的 acodec 是 none（没声音），有些 vcodec 是 none（没画面）。

然后按需拼：

# 最好画质 + 最好音频，最后合并
yt-dlp -f "bv+ba" <视频地址>

# 想要「不超过 1080p 的最好画质」，用带筛选的写法
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" <视频地址>

bv 是 bestvideo，ba 是 bestaudio，b 是合在一起的最好格式。最后那个 /b[...] 是 fallback：万一没有分离流，就退回合并格式。

判据：下载完成时如果 yt-dlp 提示「正在合并」或者你看到 .fXXX.mp4 和 .fYYY.m4a 两个文件，说明选到了分离流，这是正常的，但接下来必须有 ffmpeg。

二、没装 ffmpeg，合并这一步直接失败

选了 bv+ba 之后报错，大意是找不到 ffmpeg、无法合并音视频。yt-dlp 自己能下载，但合并是调用 ffmpeg 做的，不自带。

# 先确认到底有没有
ffmpeg -version

# Windows 上如果用包管理器
winget install Gyan.FFmpeg

# macOS
brew install ffmpeg

# Debian/Ubuntu
sudo apt install ffmpeg

装完确认 yt-dlp 能看见它：

yt-dlp --verbose <视频地址> 2>&1 | findstr -i ffmpeg

（Windows 用 findstr，Linux/macOS 换成 grep -i ffmpeg。）能在日志里看到 ffmpeg 的路径，才算真找到了。有些时候系统 PATH 里有，但 yt-dlp 是被另一个环境启动的，读到的 PATH 不一样，这一步能查出来。

判据：合并成功时输出一行，形如 Merging formats into "xxx.mp4"，并且最终只剩下一个文件。只看到一个视频文件、没有音频，或者留下两个半成品，都是没合并成。

三、两种 cookie 参数不是一回事，这是最容易踩的一个

有些视频要登录才能看完整版。yt-dlp 有两个看起来差不多的参数：

--cookies FILE                  # 从 Netscape 格式的 cookies.txt 读
--cookies-from-browser BROWSER  # 直接从浏览器里读

参数签名上，第二个还带了一串可选后缀：

--cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER]

看着很灵活（能指定 profile、能指定 Firefox 的容器），但它们不等价。yt-dlp 源码里好几个站点适配器会明确告诉你「这个站不接受 from-browser」：

# 某个企业文档站点的适配器，原文
Session cookies are required for this URL and can be passed with the --cookies option.
The --cookies-from-browser option will not work

另一个站点的提示更绕，它只在「你已经被当成订阅用户」时才提示你换参数：

The full video is for subscribers only. Only previews will be downloaded.
If you have used the --cookies-from-browser option, try using the --cookies option instead

这句话的意思是：你被识别成了免费用户，而问题可能出在 cookie 的取法上。 我当时看到「只有预览」还以为自己账号没权限，先去确认了账号，其实该做的是换参数。

所以遇到「只能下到片段 / 提示要登录 / 下到的是预览」这三类现象，排查顺序是：

1. 先用 --cookies-from-browser 试（最省事，不用手工导出）
2. 不行就手工导出 cookies.txt，改用 --cookies
3. 还不行，才去查账号权限

别把顺序反过来。先去查账号权限，很容易得出「我没买这个课所以下不了」的错误结论，然后放弃。

四、Linux 上从 Chromium 读 cookie 还要额外一个包

在 Linux 上跑 --cookies-from-browser chrome，报错说解不开 keyring。原因是 Chromium 系浏览器的 cookie 用系统密钥环加密，yt-dlp 要读它得有一个额外依赖：

pip install secretstorage

这个包在 yt-dlp 的依赖说明里标了星号，只在 Linux + Chromium 这个组合下需要。Windows 和 macOS 上不用装。

顺便记一个：Firefox 的多账户容器，用双冒号指定——

--cookies-from-browser firefox::工作

格式就是上面那个签名里的 ::CONTAINER。写错成单冒号不会报错，只会静静地用默认容器，然后你以为是 cookie 无效。

五、两个小地方，顺手记下

播放列表默认全下。 给一个课程列表地址，它会从第一集下到最后一集。只想下其中几集要显式限定：

yt-dlp --playlist-items 3,5,7-9 <列表地址>

想先看看会下哪些、不真下，加 --flat-playlist --print title，只打印标题。

并发不是越大越好。 加 -N 4 走分片并发下载能快一些，但一些站点会限速甚至断连。测到稳定的值就停，别一路加。真要提速，先看是不是单线程就在跑满带宽了。

最后

这四类问题的共同点是：都不报「你参数写错了」。画质低、只有预览、留下两个文件、静默用了默认容器——每一个都成功退出了，只是结果不是你要的。

所以每次下完，别只看命令有没有报错，去看三个东西：最终是不是只剩一个文件、分辨率对不对、时长和原视频一致不。这三个对上了，才算真下到了。