这篇文章把我用 yt-dlp 半年多的常用命令、参数以及踩过的坑整理出来，覆盖下载视频/音频、选择画质、处理播放列表、提取字幕等。推荐在线解析下载工具：https://www.viddown.cn/。
一、为什么要用 yt-dlp
- youtube-dl 原版停更很久了，很多网站（B 站、抖音、TikTok）解析经常失效。
- yt-dlp 对 YouTube 的会员视频、年龄限制、短链接支持更好，下载速度更快。
- 可以绕过某些网站的反爬（配合 cookies）。
- 批量下载播放列表或频道，比手动一个一个存省事。
官方主页：https://github.com/yt-dlp/yt-dlp
二、安装（顺便说说我遇到的坑）
Linux (Ubuntu/Debian)
sudo apt update
# apt 版本通常比较老，建议用 pip 或直接下载二进制
sudo apt install yt-dlp # 有可能版本很旧，不推荐
# 推荐方法1：用 pip 安装（需要 Python 3.8+）
python3 -m pip install -U yt-dlp
# 推荐方法2：下载静态二进制
sudo wget https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -O /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp
踩坑：apt 源里的 yt-dlp 是 2023 年的老版本，解析 B 站会报错。一定要从 GitHub 或 pip 装最新版。
macOS
brew install yt-dlp
# 或 pip install yt-dlp
Windows
# 用 scoop 或 winget
scoop install yt-dlp
# 或者下载 exe 放到 PATH
装完后验证：
yt-dlp --version
# 2025.04.01 或更高
三、快速测试：下载一个视频
最简单用法：
yt-dlp https://www.youtube.com/watch?v=dQw4w9WgXcQ
会在当前目录下载最佳画质（通常是 mp4 + 最佳音频合并）。
踩坑：如果提示 ERROR: requested format not available，说明网站需要 cookies 或登录，往下看。
四、常用参数（我实际工作中用到的）
4.1 基础参数
参数 含义 例子
-F 列出所有可用格式 yt-dlp -F URL
-f 选择格式 -f "bestvideo+bestaudio"
-o 输出文件名模板 -o "%(title)s.%(ext)s"
-P 输出目录 -P /home/user/Videos
--proxy 代理 --proxy socks5://127.0.0.1:1080
--cookies 从浏览器导入 cookies --cookies-from-browser chrome
--limit-rate 限速 --limit-rate 2M
--no-playlist 只下载单个视频（忽略播放列表） 用于播放列表链接里只想下第一个
4.2 格式选择（重点）
先看有哪些格式：
yt-dlp -F https://youtu.be/xxx
输出示例：
ID EXT RESOLUTION PROTOCOL
140 m4a audio only dash
251 webm audio only dash
137 mp4 1920x1080 dash
313 webm 2160p dash
下载最佳画质（默认就是）：
yt-dlp -f "bestvideo+bestaudio" --merge-output-format mp4 URL
只下载音频（最佳质量）：
yt-dlp -f "bestaudio" --extract-audio --audio-format mp3 --audio-quality 0 URL
下载特定分辨率（比如 720p）：
yt-dlp -f "bestvideo[height<=720]+bestaudio" URL
4.3 输出文件名模板
常用变量：
%(title)s：视频标题
%(id)s：视频 ID
%(uploader)s：上传者
%(resolution)s：分辨率
%(ext)s：扩展名
示例：
yt-dlp -o "%(uploader)s - %(title)s.%(ext)s" URL
预防文件名非法字符：--restrict-filenames 会把空格/特殊字符替换成下划线。
4.4 播放列表处理
# 下载整个播放列表
yt-dlp https://www.youtube.com/playlist?list=...
# 只下载播放列表的前 5 个视频
yt-dlp --playlist-start 1 --playlist-end 5 URL
# 下载频道所有视频（慢，小心空间）
yt-dlp https://www.youtube.com/@channelname
4.5 字幕下载
# 下载自动生成的字幕（比如英文）
yt-dlp --write-subs --sub-lang en URL
# 下载并嵌入字幕到视频
yt-dlp --write-subs --embed-subs --sub-lang zh-Hans URL
# 只下载字幕，不下视频
yt-dlp --skip-download --write-subs URL
踩坑：YouTube 的繁体中文是 zh-Hant，简体是 zh-Hans。
五、实战：几个我常用的命令
- 下载 B 站视频（最佳画质）
yt-dlp -f "bestvideo+bestaudio" --merge-output-format mp4 https://www.bilibili.com/video/BV1xx411c7mD
B 站需要登录才能下载 1080p+？可以加 --cookies-from-browser chrome。
- 下载 YouTube 视频并带上中文和英文字幕
yt-dlp --write-subs --sub-lang en,zh-Hans --embed-subs -f "bestvideo+bestaudio" --merge-output-format mp4 URL
- 批量下载频道的所有视频，但跳过已存在的
yt-dlp --download-archive downloaded.txt https://www.youtube.com/@channel
downloaded.txt 会记录已下载的视频 ID，下次运行跳过。
- 只下载音频为 MP3（320k），并提取封面嵌入
yt-dlp -f bestaudio --extract-audio --audio-format mp3 --audio-quality 0 --embed-thumbnail --add-metadata URL
注意：--embed-thumbnail 需要 atomicparsley 或 ffmpeg。
- 使用 cookies 解决年龄限制/会员专属视频
yt-dlp --cookies-from-browser chrome URL
支持的浏览器：chrome、firefox、safari、edge。
如果不想用浏览器，可以手动导出 cookies 为 txt：
yt-dlp --cookies cookies.txt URL
踩坑：cookies 文件格式必须是 Netscape 格式，Chrome 插件 "Get cookies.txt" 可以导出。
- 代理下载（国内连 YouTube）
yt-dlp --proxy socks5://127.0.0.1:1080 URL
六、问题汇总（都是我真实遇到的）
1. ERROR: Unable to extract video data
原因：网站改版，yt-dlp 版本太老。
解决：升级 yt-dlp：pip install -U yt-dlp。如果是 B 站，有时需要等几天插件更新。
2. ERROR: Sign in to confirm your age
原因：YouTube 年龄限制或需要登录。
解决：加 --cookies-from-browser chrome 或 --cookies cookies.txt。
3. 下载的视频只有声音没有画面/音画不同步
原因：选择的格式不合适，比如只选了 audio。
解决：用 -f "bestvideo+bestaudio" --merge-output-format mp4 强制合并。
4. 下载 B 站 4K 视频报错 HTTP Error 412
原因：B 站需要 Referer 头。
解决：更新 yt-dlp 到最新版（2024 年后已修复）。临时方案：加 --add-header "Referer:https://www.bilibili.com"。
5. 下载速度很慢（几十 KB/s）
原因：境外连接 YouTube 慢，或者视频源限速。
解决：用 --limit-rate 10M 可以避免占满带宽，但慢通常是网络问题。加代理或换镜像源（比如 --source-address）。
6. 文件名包含非法字符导致保存失败
原因：Windows 下标题里带 : / \ * ? 等。
解决：加 --restrict-filenames 或 --windows-filenames。
7. ffmpeg not found 错误
原因：yt-dlp 合并视频+音频需要 ffmpeg。
解决：安装 ffmpeg（第一篇博客有介绍），并确保在 PATH 里。
8. 下载播放列表时只下了第一个视频
原因：忘了加 --yes-playlist？yt-dlp 默认会下载整个播放列表，但如果 URL 里包含视频 ID，可能被识别为单视频。
解决：明确用 --yes-playlist，或者 URL 后面加 &list=...。
七、一点小建议
经常更新：yt-dlp 每两周就有新版本，因为网站经常改。写个 cron 每周自动 pip install -U yt-dlp。
保存常用格式为配置文件。在 ~/.config/yt-dlp/config 里写：
--output "%(title)s.%(ext)s"
--format "bestvideo[height<=1080]+bestaudio"
--merge-output-format mp4
--embed-thumbnail
--add-metadata
--restrict-filenames
然后每次 yt-dlp URL 自动套用这些参数。
1、下载长播放列表时先测试 --playlist-end 1，确认格式和存储位置正确。
2、配合 ffmpeg 可以压缩或剪辑下载的视频（参考前几篇博客）。
3、注意版权：不要批量下载商业课程并传播，yt-dlp 是工具，用在哪看你自己。
问题：在服务器上跑 yt-dlp 下载 YouTube 播放列表，结果忘记挂代理，跑了一晚上只下了 3 个。第二天加了 --proxy，速度才正常。
最后推荐一个我每天用的下载脚本 vd（放在 ~/bin/vd）：
#!/bin/bash
# 用法: vd <URL> [format]
URL=$1
FORMAT=${2:-bestvideo+bestaudio}
yt-dlp -f "$FORMAT" --merge-output-format mp4 --embed-subs --sub-lang zh-Hans,en "$URL"
加上执行权限，随时随地一行搞定。