yt-dlp 新手教程

yt-dlp 新手教程

一个命令行音视频下载器：把「解析网站 → 选清晰度 → 下载 → 合并音视频」压成一条命令。给谁：想让下载这件事可脚本、可批量、可复制粘贴命令的人。

命令行 CLI 开源免费 youtube-dl 活跃分支 GitHub 仓库

1这是什么

一句话：yt-dlp 是一个用 Python 写的命令行下载器，能从 1000+ 网站抓取音频和视频。

你在浏览器里能看到的视频，绝大多数它都能下载：YouTube、Bilibili、Twitter/X、Instagram、Twitch、播客站点……核心思想是「网站会变，工具不变」——每个网站对应一个 extractor（抽取器），站点改版时社区更新 extractor，你的使用习惯一行不用改。

1000+
支持的网站
1 条
命令完成下载
3 个
更新通道 stable / nightly / master
0 元
免费开源，无广告

它是 youtube-dl 的分支（fork）：原版自 2021 年起几乎停更，yt-dlp 修掉了历史积压的 bug，还加了一堆原版没有的能力（SponsorBlock 跳过赞助片段、分片多线程下载、更灵活的格式选择器等），如今已是事实上的标准替代品。

它不做什么：不能下载 DRM 加密内容（如 Netflix 会员影片）；不是 BT/磁力下载器；本身不做格式转换（转码靠 FFmpeg 配合）；也不是图形界面软件——所有操作都在终端里完成。

2为什么需要它

下载视频的常见路子都有硬伤，yt-dlp 把它们逐个解决。

常见做法痛点yt-dlp 的答案
「在线解析」网站满屏广告、限速、经常失效，视频稍长就失败本地运行，速度只取决于你的网络，永不弹广告
浏览器录屏实时 1:1 耗时，画质有损，声音混进系统音直接拿原始码流，画质无损、速度可数倍于播放速度
youtube-dl 原版2021 年后基本停更，网站一改版就报错，下载慢活跃维护、release 频繁，支持站点和功能持续增加

核心洞察：把「解析 + 选择 + 下载 + 合并 + 改名归档」做成一条可组合的管道。想要 mp3？加两个参数。要整个收藏夹？换个 URL。要跳过赞助片段？加一个 flag。所有需求都是参数组合，而不是换工具。

3核心流程

一条命令背后，yt-dlp 干了五件事。

提交 URL 任意支持站点 解析站点 extractor 抽流 选格式 -f 与 -S 下载 分片并发 后处理 ffmpeg 合并 从 URL 到本地文件的全流程，每一步都有对应参数可以干预 提交 URL 任意支持站点 解析站点 extractor 抽流 选格式 -f 与 -S 下载 分片并发 后处理 ffmpeg 合并输出 每一步都有参数可以干预

其中第 2 步「解析」是 yt-dlp 的灵魂：它假装成浏览器访问页面，把网页里藏起来的真实视频流地址、字幕地址、元数据全部挖出来，整理成一份格式清单交给你。第 3 步你不指定的话，它会按内置的默认偏好（优先 h264 编码 + 最佳音质）自动选。

4安装

按你的系统选一条路。注意「独立二进制」和「pip 安装」是两条不同的升级路径，别混着来。

平台推荐方式命令 / 说明
Windows独立 exewinget install yt-dlp，或到 Releases 下载 yt-dlp.exe
macOSHomebrewbrew install yt-dlp
Linux官方二进制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
有 Python 3.10+pippython3 -m pip install -U "yt-dlp[default]"
易混淆的两条路：独立二进制（exe / brew / curl 装的）用 yt-dlp -U 自更新；pip 装的版本 -U 会报「无法更新」，要用 pip install -U 升级。另外包管理器仓库里的版本经常滞后（apt 装的尤其老），遇到奇怪 bug 先怀疑版本旧。
必须同时装 FFmpeg：高清视频的音轨和画面是分开的两条流，下载完要靠 FFmpeg 合并；提取 mp3、嵌入封面也都靠它。没装 FFmpeg，yt-dlp 只能下到低清晰度的预合并版本。macOS brew install ffmpeg，Windows winget install ffmpeg。

5环境自检

三条命令确认环境健康，再开始干活。

yt-dlp --version          # 打印版本号，能输出就说明装对了
ffmpeg -version           # FFmpeg 在不在、版本多少（太旧会有转码 bug）
yt-dlp -U                 # 检查更新；pip 版会提示用 pip 升级，属正常

关键二选一：如果你只追求「能用、好升级」，选 brew / winget / 官方二进制；如果你要把它当 Python 库嵌进自己的脚本、或装 nightly 抢新功能，选 pip。绝大多数人选前者就够了。

6第一次实战

五条命令，从零到拿到 mp3，全部可直接照抄。

# 1. 最朴素：下载一个视频，存到当前目录
yt-dlp "https://www.youtube.com/watch?v=BaW_jenozKc"

# 2. 先看有哪些清晰度可选（不下载）
yt-dlp -F "https://www.youtube.com/watch?v=BaW_jenozKc"

# 3. 只要音频，转成 mp3（最高音质）
yt-dlp -x --audio-format mp3 --audio-quality 0 "https://www.youtube.com/watch?v=BaW_jenozKc"

# 4. 下载整个播放列表，文件名带序号
yt-dlp -o "%(playlist_index)02d - %(title)s.%(ext)s" "播放列表URL"

# 5. 带中英字幕并嵌入视频
yt-dlp --write-subs --sub-langs "zh.*,en" --embed-subs "https://www.youtube.com/watch?v=BaW_jenozKc"
注意 URL 一定要用引号包起来——很多视频链接里带 &，不包引号 shell 会把它当「后台运行」处理，直接报错。

7产物结构

yt-dlp 会生成哪些文件、各自是干嘛的。

文件怎么产生用途
标题.mp4 / .mkv / .webm默认输出正主，音视频成品
*.f137.mp4 之类合并前的临时分轨音视频合完就自动删，看到残留说明上次没跑完
*.part下载中断断点续传的进度文件，重跑同一命令会接着下
*.vtt / *.srt--write-subs外挂字幕文件
*.info.json--write-info-json标题、描述、时长等全部元数据，适合脚本二次加工
archive.txt--download-archive已下载 ID 清单，用来去重

设计原则：一切文件名都由 -o 输出模板决定，默认是「标题.扩展名」。标题里有什么字符、存到哪个目录、按什么规则编号，全部可以模板化控制。

8日常怎么用

记住一个心法：默认命令已经很好，只在有明确需求时加参数。

# 默认就是「最佳画质自动合并」，什么都不用加
yt-dlp "URL"

# 明确要求 最佳视频流 + 最佳音频流，不行就退而求其次
yt-dlp -f "bv*+ba/b" "URL"

# 只要 1080p 以内、压制为 mp4（老设备兼容）
yt-dlp -S "res:1080" -t mp4 "URL"

# 播放列表只下前 5 集，跳过直播中视频
yt-dlp -I 1:5 --match-filters "!is_live" "播放列表URL"

# 限速 5MB/s，别占满全家带宽
yt-dlp -r 5M "URL"

用了会发生什么：下载中断重跑同一命令会断点续传；重复下载同一个视频会重新解析并覆盖/续传；播放列表默认全下。

不会发生什么：不会绕过 DRM；不会在你没指定的情况下做转码重压缩（--remux-video 只换容器不损画质）；不会上传你机器上的任何东西。

9进阶玩法

四个最能拉开效率差距的能力。

输出模板 -o

文件名随便捏：-o "%(upload_date>%Y-%m-%d)s %(title).80B.%(ext)s" 按上传日期 + 截断标题命名。支持算术、日期格式化、默认值，是个迷你模板语言。

下载存档去重

--download-archive archive.txt：下过的视频记一笔，下次批量任务自动跳过。配合定时任务就是「收藏夹自动备份机」。

借浏览器的登录态

会员视频、年龄限制视频：--cookies-from-browser chrome（或 firefox/edge），直接复用浏览器里已登录的 cookies，不用账号密码。

跳过赞助片段

基于 SponsorBlock 社区数据：--sponsorblock-remove sponsor，把求三连、广告口播整段剪掉，不用重新编码。

还有一个隐藏大招：配置文件。把你常用的参数写进配置，之后命令里只打 yt-dlp URL：

# 配置文件位置：macOS ~/Library/Application Support/yt-dlp/config
#              Windows %APPDATA%\yt-dlp\config
#              Linux ~/.config/yt-dlp/config
# 内容示例（一行一个参数）：
-o ~/Downloads/%(title)s.%(ext)s
--embed-thumbnail
--embed-metadata
--sponsorblock-remove sponsor

10不止是「下视频」

名字里只有 dl，实际是个媒体抓取瑞士军刀。

播客仓库

播客站点多为纯音频，-x --audio-format mp3 -o "%(series)s/%(upload_date)s %(title)s.%(ext)s" 按节目归档，还自动嵌封面。

给 AI 转写备料

字幕一条命令到手：--write-auto-subs --sub-langs "zh.*" --skip-download。连视频都不用下，只拿字幕文件喂给大模型做摘要。

收藏夹自动备份

--download-archive + cron / 定时脚本，把「我喜欢」列表变成只增不减的本地库，源站下架也不怕。

直播与回放

支持直播流录制与直播回放抓取；Twitch、YouTube 直播都能处理，配合 --live-from-start 还能从直播开头开始录。

11性能与成本

免费软件，成本为零；速度的上限由网站和你说了算。

维度表现说明
金钱成本0开源免费，无会员无广告无内购
下载速度取决于站点限速分片式站点可用 --concurrent-fragments 4 并发提速；部分站点服务端限速，参数救不了
磁盘占用≈ 视频原始体积下载过程临时多占一份音视频分轨，合并后自动清理
CPU很低默认只合并不转码，几乎不耗 CPU；要求 --recode-video 重编码才吃 CPU
一句话结论：默认配置已是「快且省」的状态，只有批量爬大列表时才需要考虑限速与并发参数。

12FAQ 与踩坑

新手最常撞的几堵墙，每条都给可直接执行的解法。

命令一跑就报错，URL 里带 & 的是重灾区
shell 把 & 当成「后台运行」。解决：永远给 URL 加引号 yt-dlp "https://...&v=xxx"，或转义 \&。
HTTP Error 429 / 403，下不动了
429 是请求太频繁被站点限流：停一会儿、降低并发、或挂 --proxy 换出口 IP。403 常是 Cloudflare 拦截：在浏览器里正常访问一次目标站，然后用 --cookies-from-browser firefox --user-agent "浏览器完整UA" 借登录态（Firefox 的 cookies 效果最好）。
会员视频 / 年龄限制视频下不了
先在浏览器登录该网站，再 yt-dlp --cookies-from-browser chrome "URL"。想长期复用可导出 cookies 文件：--cookies-from-browser chrome --cookies cookies.txt，以后用 --cookies cookies.txt。
Windows 下输出模板报错
批处理文件里 % 要写成 %%：-o "%%(title)s.%%(ext)s"。直接在命令行交互执行则不用转义。
文件名太长，保存失败
用模板截断：-o "%(uploader).30B - %(title).200B.%(ext)s"（.30B 表示最多 30 字节）。写进配置文件一劳永逸。
ffmpeg 报 incorrect codec parameters
FFmpeg 版本太旧对 Opus 等新编码支持不全。先升级 FFmpeg；急用可临时加 --postprocessor-args "ffmpeg:-strict -2" 绕过。
YouTube 只能下到 720p？
不是 bug：高清晰度的音视频是分开的两条流，必须靠 FFmpeg 合并。装好 FFmpeg 后默认就会下最佳画质再自动合并；用 -F 能亲眼看到那些分开的流。
版本太旧、网站改版后报错
先升级再怀疑别的：yt-dlp -U（二进制）或 pip install -U yt-dlp。仍不行可切 nightly 抢修：yt-dlp --update-to nightly。报 issue 时官方也要求附 -Uv 的完整日志。

yt-dlp 新手教程 · 基于 yt-dlp 官方文档整理