yt-dlp 是什么
yt-dlp 是开源命令行下载工具 youtube-dl 的活跃分支，沿用了 youtube-dl 的命令行习惯，但在更新频率、下载速度、绕过站点限速与新站点适配方面都远胜原版。截至 2026 年，yt-dlp 通过内置 extractor 支持上千个站点，覆盖 YouTube、Bilibili、Niconico、Crunchyroll、ABEMA、Twitter/X、Vimeo 等主流音视频平台。
它的核心工作模式是：解析页面 → 列出可用音视频流 → 按你给的格式选择规则挑选 → 分别下载 → 调用 ffmpeg 合并封装。这意味着两件事：
- 高画质（如 1080P+）通常是"纯视频流 + 纯音频流"分离提供，必须用 ffmpeg 合并才能得到一个完整文件。
- yt-dlp 本身只负责"下载与选择"，强依赖 ffmpeg 完成合并、转封装、烧录字幕等操作。没装 ffmpeg，高画质就会失败。
安装 yt-dlp 与 ffmpeg
yt-dlp 是单文件 Python 程序，三种安装方式任选其一；但 ffmpeg 必须单独安装，否则合并、烧字幕、转封装都会失败。
winget install yt-dlp；或从 GitHub Releases 下载 yt-dlp.exe 放入 PATH 目录。ffmpeg 同理：winget install ffmpeg，或下载解压后将 bin 目录加入系统 PATH。完成后在 PowerShell 执行 yt-dlp --version 与 ffmpeg -version 验证。brew install yt-dlp ffmpeg。装完即用，无需手动配 PATH。pip install -U yt-dlp（建议在虚拟环境或加 --user）；发行版自带 yt-dlp 包可能偏旧。也可直接下载 binary：sudo curl -L 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。ffmpeg 用 sudo apt install ffmpeg（Debian/Ubuntu）或 sudo dnf install ffmpeg（Fedora）。安装完成后，统一用下面两条命令验证（能看到版本号即成功）：
yt-dlp --version
ffmpeg -versionyt-dlp --ffmpeg-location /usr/local/bin <URL>，或在配置文件 ~/.config/yt-dlp/config（Windows 为 %APPDATA%\yt-dlp\config）里写入 --ffmpeg-location 一行，永久生效。
基本用法
最简单的下载方式——直接给一个 URL，yt-dlp 会按默认规则选最佳画质合并：
yt-dlp https://www.youtube.com/watch?v=XXXXXXXXXXX下载前先查看该视频有哪些可用格式，这是排查画质问题与会员内容的第一步：
yt-dlp -F https://www.youtube.com/watch?v=XXXXXXXXXXX-F（大写）会列出所有音视频流的 ID、扩展名、分辨率、码率。记下你想要的视频流 ID 和音频流 ID，再用 -f 指定：
yt-dlp -f 137+140 https://www.youtube.com/watch?v=XXXXXXXXXXX上例中 137 是 1080P 视频流、140 是 m4a 音频流，+ 表示合并。这是最底层、最可控的写法。
选画质与合并
手动查 ID 太繁琐，实际更常用格式选择表达式。下面这条命令是 99% 场景下的万能画质命令：
yt-dlp -f "bv*+ba/b" https://www.youtube.com/watch?v=XXXXXXXXXXX解释：bv* = 最佳视频流（任意编码）、ba = 最佳音频流、/b = 若站点只提供单文件流则退化为最佳单文件。该写法自动选最高画质并合并。
限制最高 1080P（避免下到 4K 占空间）：
yt-dlp -f "bv*[height<=1080]+ba/b" https://www.youtube.com/watch?v=XXXXXXXXXXX强制合并为 mp4 容器（部分播放器只认 mp4）：
yt-dlp -f "bv*+ba/b" --merge-output-format mp4 https://www.youtube.com/watch?v=XXXXXXXXXXX用 -S 参数按字段排序选流，比 -f 更直观。例如"优先 1080P、优先 mp4、优先 av1 编码"：
yt-dlp -S "res:1080,ext:mp4:vcodec:av1" https://www.youtube.com/watch?v=XXXXXXXXXXX字幕下载
yt-dlp 支持下载人工字幕与自动生成字幕，并可嵌入到视频文件中。基础命令：
yt-dlp --write-subs --sub-langs "zh,en" --embed-subs \
https://www.youtube.com/watch?v=XXXXXXXXXXX参数含义：--write-subs 写出字幕文件（.srt/.vtt）、--sub-langs 指定语言（多个用逗号，all 表示全部）、--embed-subs 把字幕嵌入到视频容器里（需 ffmpeg）。
下载自动生成字幕（YouTube 自动语音识别字幕）：
yt-dlp --write-auto-subs --sub-langs "zh-Hans,en" \
--embed-subs https://www.youtube.com/watch?v=XXXXXXXXXXX烧录字幕到画面（硬字幕，无需播放器加载字幕文件）需要 ffmpeg 实际转码，建议封装为 mkv 或 mp4：
yt-dlp --write-subs --sub-langs "zh,en" \
--embed-subs --merge-output-format mkv \
https://www.youtube.com/watch?v=XXXXXXXXXXX--embed-subs 默认是软字幕（保留为容器内轨道，可在播放器开关）。要烧成画面的一部分（硬字幕）需配合 --postprocessor-args "subtitles=-c:v libx264" 触发 ffmpeg 重编码，但耗时较长，非必要不建议。
批量下载番剧
yt-dlp 把整个播放列表当作多个条目处理，直接传播放列表 URL 即下载全部：
yt-dlp https://www.youtube.com/playlist?list=PLXXXXXXXXXXXXXXXX用 --download-archive 记录已下载条目，跳过已下载的集数，断点续刷非常方便：
yt-dlp --download-archive done.txt \
https://www.youtube.com/playlist?list=PLXXXXXXXXXXXXXXXX用 -a（或 --batch-file）从文本文件批量读取 URL，每行一个：
yt-dlp -a list.txt --download-archive done.txt番剧场景下，按集数命名输出文件最关键。用 -o 指定输出模板：
yt-dlp -o "%(uploader)s/%(title)s/%(title)s-E%(episode_number)s.%(ext)s" \
--download-archive done.txt \
--merge-output-format mp4 \
https://www.youtube.com/playlist?list=PLXXXXXXXXXXXXXXXX常用模板字段：%(uploader)s 上传者、%(title)s 标题、%(episode_number)s 集数（自动补零需用 >=02 等格式化语法）、%(upload_date)s 上传日期、%(ext)s 扩展名。例如：
yt-dlp -o "%(series)s/Season %(season_number)s/%(series)s-S%(season_number)sE%(episode_number)s.%(ext)s" \
<播放列表URL>--download-archive done.txt --merge-output-format mp4 --embed-metadata --embed-subs --sub-langs "zh,en" 一条命令，即可把整部番剧按"番剧名/季/番剧名-S01E01.mp4（含字幕与元数据）"结构归档，新增集数时只需重跑同一条命令，已下的自动跳过。
进阶常用参数
处理会员站点时，把浏览器登录后的 cookie 导出为 Netscape 格式文件，让 yt-dlp 以登录态访问：
yt-dlp --cookies cookies.txt <URL>cookie 可用浏览器扩展（如 Get cookies.txt LOCALLY）导出。切勿分享 cookie 文件，等同账号密码。
断点续传（下载中断后继续，不会重头来）：
yt-dlp -c <URL>多线程下载分片，明显提升大文件速度：
yt-dlp --concurrent-fragments 4 <URL>走代理（适用于地区限制或需要科学上网的站点）：
yt-dlp --proxy "socks5://127.0.0.1:7890" <URL>标记/移除 SponsorBlock 广告段落（针对 YouTube 等支持的站点，自动跳过赞助广告与片头片尾）：
yt-dlp --sponsorblock-mark all --sponsorblock-remove default <URL>常见错误与解决
ffmpeg -version 能输出版本号再重试。临时方案：--ffmpeg-location <路径> 显式指定。--cookies cookies.txt 携带登录 cookie；②换 UA：--user-agent "Mozilla/5.0 ..."；③针对部分站点用 --extractor-args "youtube:player_client=android" 等切换客户端类型；④升级到最新版 yt-dlp：yt-dlp -U 或 pip install -U yt-dlp。--proxy "socks5://127.0.0.1:7890"。代理客户端配置见 《Mihomo Party 使用教程》。--concurrent-fragments 4（或更高 8/16）；若是站点限速，可尝试切换 player_client（见上）；检查代理带宽是否瓶颈。--list-subs <URL> 查看该视频实际有哪些字幕语言与语言代码（如 zh-Hans 而非 zh），再据此调整 --sub-langs。常见问题 FAQ
Q1：能下载 B 站 / YouTube 上的动漫吗？
技术上 yt-dlp 同时支持 Bilibili 与 YouTube 的下载。但请只下载你拥有合法权限的内容——公共领域、CC 协议、官方允许下载的预告片/花絮、或你已购会员内容的离线副本。下载并传播受版权保护的正版番剧违反版权法与平台服务条款，本站不支持。
Q2：会员内容怎么下载？
用 --cookies cookies.txt 携带你的登录态（cookie 可用浏览器扩展导出为 Netscape 格式）。注意：仅限下载你本人已购买的会员内容用于离线观看，不可转售或公开传播。cookie 文件等同账号凭据，请妥善保管。
Q3：下载完发现没有字幕怎么办？
先用 yt-dlp --list-subs <URL> 查看可用字幕列表，确认语言代码（YouTube 简中常为 zh-Hans 而非 zh）。再带 --write-subs --sub-langs "<正确代码>" --embed-subs 重新下载。若该视频只有自动字幕，改用 --write-auto-subs。
Q4：如何只下载音频做成 MP3？
用 -x（extract-audio）触发音频提取，--audio-format mp3 指定目标格式（需 ffmpeg）：
yt-dlp -x --audio-format mp3 --audio-quality 0 <URL>--audio-quality 0 表示最佳质量（0-10，越小越好）。常用于下载动漫 OP/EP 单曲。