yt-dlp 视频音频下载
yt-dlp 是命令行视频/音频下载工具，支持 1700+ 个网站（YouTube、Bilibili、Twitter/X、TikTok 等）。当用户需要下载视频或音频时，指导使用此工具。
前置条件
检查 yt-dlp 是否已安装：
yt-dlp --version
未安装则引导用户安装：
brew install yt-dlp # macOS
pip install -U yt-dlp # 全平台通用
推荐安装 ffmpeg（音视频合并、格式转换）：
brew install ffmpeg
核心命令速查
| 场景 | 命令 |
|---|---|
| 下载视频（自动最佳格式） | yt-dlp "URL" |
| 下载为 MP3 | yt-dlp -x --audio-format mp3 "URL" |
| 下载为 M4A | yt-dlp -x --audio-format m4a "URL" |
| 下载为 FLAC（无损） | yt-dlp -x --audio-format flac "URL" |
| 查看可用格式 | yt-dlp -F "URL" |
| 选择 1080p | yt-dlp -f "bestvideo[height<=1080]+bestaudio" "URL" |
| 选择 720p | yt-dlp -f "bestvideo[height<=720]+bestaudio/best[height<=720]" "URL" |
| 强制 MP4 格式 | yt-dlp -t mp4 "URL" |
| 下载播放列表 | yt-dlp "PLAYLIST_URL" |
| 下载播放列表第 1-5 个 | yt-dlp -I 1:5 "PLAYLIST_URL" |
| 仅下载单个视频（忽略播放列表） | yt-dlp --no-playlist "URL" |
| 批量下载 | yt-dlp -a urls.txt |
| 下载字幕 | yt-dlp --write-subs --sub-langs zh,en "URL" |
| 嵌入字幕到视频 | yt-dlp --write-subs --embed-subs "URL" |
| 嵌入封面+元数据 | yt-dlp --embed-thumbnail --embed-metadata "URL" |
| 去除赞助商片段 | yt-dlp --sponsorblock-remove sponsor "URL" |
| 从浏览器读 Cookie | yt-dlp --cookies-from-browser chrome "URL" |
| 更新 yt-dlp | yt-dlp -U |
代理配置（中国大陆用户）
下载 YouTube 等被 GFW 封锁的网站需要代理：
# SOCKS5 代理（推荐 socks5h，通过代理解析 DNS）
yt-dlp --proxy "socks5h://127.0.0.1:7891" "URL"
# HTTP 代理
yt-dlp --proxy "http://127.0.0.1:7890" "URL"
# 下载国内视频时禁用代理
yt-dlp --proxy "" "URL"
推荐写入配置文件 ~/.config/yt-dlp/config：
--proxy socks5h://127.0.0.1:7891
--geo-bypass
-o "%(title)s [%(id)s].%(ext)s"
-w
-c
--embed-metadata
--embed-thumbnail
常用代理端口：Clash HTTP=7890 / SOCKS5=7891，V2Ray SOCKS5=10808。
输出模板
yt-dlp -o "%(channel)s/%(title)s.%(ext)s" "URL" # 按频道分目录
yt-dlp -o "%(upload_date)s - %(title)s.%(ext)s" "URL" # 按日期命名
yt-dlp -o "%(playlist_index)s - %(title)s.%(ext)s" "URL" # 播放列表带序号
yt-dlp --restrict-filenames -o "%(title)s.%(ext)s" "URL" # ASCII 文件名
常用字段：%(title)s 标题、%(id)s 视频ID、%(ext)s 扩展名、%(channel)s 频道名、%(upload_date)s 日期、%(playlist_index)s 序号。
常见问题
| 问题 | 解决方案 |
|---|---|
| 下载失败 / 网络超时 | 加代理：--proxy "socks5h://127.0.0.1:7891" |
| ffmpeg not found | brew install ffmpeg |
| 下载速度慢 | -N 4（并发分片）或 --downloader aria2c |
| "Sign in to confirm you're not a bot" | --cookies-from-browser chrome 或 --impersonate chrome |
| 播放列表下载了太多内容 | 加 --no-playlist 只下载当前视频 |
| 文件名乱码 | --restrict-filenames |
| 播放列表中断后继续 | --download-archive archive.txt（自动跳过已下载） |
| 版本过旧导致失败 | yt-dlp -U |
注意事项
- URL 中的
list=RD...是 YouTube 自动生成的 Mix 播放列表（可能几百首），用--no-playlist避免 - 使用
socks5h://而非socks5://，带 h 表示通过代理解析 DNS - 音频质量：
--audio-quality 0（最佳）到--audio-quality 10（最差），默认 5 - 预设别名：
-t mp3、-t mp4、-t mkv可简化常用操作
