---

slug: yt-dlp-toolkit name: yt-dlp displayName: 视频下载 媒体提取 批量处理 description: 命令行视频下载工具，支持千站资源获取与格式转换。 version: 1.3.8 rules_version: cpr-20260815-n451 license: MIT source_project: original source_url: https://github.com/bluebigman/skill-factory-originals/tree/main/yt-dlp-toolkit copyright_holder: 原创作者（自持版权） ai_generated: true ai_tools: ["DeepSeek"] disclaimer: 本Skill由AI辅助生成，提供使用指导和最佳实践。使用前请阅读相关文档。 author: LinguaForge Studio agent_created: true trigger_words: ["yt-dlp", "视频下载", "音频提取", "批量下载", "播放列表", "youtube-dl"]

---

⚠️ 本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。

本内容由 AI 生成，仅供学习参考

yt-dlp 命令行媒体获取工具

一、能力边界速查卡

1.1 工具定位

yt-dlp 是一款基于命令行的媒体资源获取程序，能够从包括 YouTube、Bilibili、Vimeo 在内的数千个网站提取视频或音频流。它支持完整的播放列表递归处理、元数据抓取、格式筛选与后处理转换。

1.2 明确能做

能力项	说明	示例
单视频下载	下载指定 URL 的视频文件	yt-dlp "https://example.com/watch?v=abc"
音频提取	仅提取音频流并转为 mp3	yt-dlp -x --audio-format mp3 <URL>
播放列表批量	递归下载整个播放列表	yt-dlp -f best <playlist_url>
格式筛选	按分辨率/编码/大小选择流	yt-dlp -f "bv*[height<=1080]+ba" <URL>
元数据输出	以 JSON 格式输出视频信息	yt-dlp -J <URL>
字幕下载	获取视频字幕文件	yt-dlp --write-subs --sub-langs zh-Hans <URL>
断点续传	中断后重新执行可跳过已下载部分	yt-dlp -c <URL>
限速控制	限制下载带宽	yt-dlp -r 1M <URL>

1.3 明确不能做

限制项	说明
绕过 DRM 加密	无法解密 Widevine、FairPlay 等商业版权保护内容
突破地域封锁	不包含代理/VPN 功能，需用户自行配置网络环境
下载需登录的付费内容	仅支持通过 cookies 文件模拟已登录状态，无法破解付费墙
实时流录制	不支持 RTMP/HLS 直播流的实时录制（仅支持 VOD 点播）
保证下载成功率	网站结构变更、服务器限流均可能导致失败

1.4 适用对象

• 需要批量保存教学视频的教育工作者
• 需要提取音频素材进行二次创作的内容创作者
• 需要离线备份公开视频资料的研究人员
• 需要自动化媒体采集流程的运维工程师

---

二、触发方式与场景映射

2.1 触发词

当用户输入包含以下关键词时，本 Skill 被激活：

• 核心触发：yt-dlp、youtube-dl
• 场景触发：视频下载、音频提取、批量下载、播放列表
• 补充触发：扒视频、存视频、下歌、拉取视频

2.2 用户意图映射表

用户说（大白话）	实际需求	对应命令模式
"帮我把这个视频存下来"	下载单个视频，默认最高画质	yt-dlp <URL>
"只要声音，转成 mp3"	提取音频并转格式	yt-dlp -x --audio-format mp3 <URL>
"这个歌单全部下载"	批量下载播放列表	yt-dlp -f best <playlist_url>
"要 1080p 的，不要 4K"	按分辨率筛选	yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" <URL>
"下载带中文字幕的"	获取字幕文件	yt-dlp --write-subs --sub-langs zh-Hans <URL>
"看看这个视频的信息"	输出元数据	yt-dlp -J <URL>

---

三、标准操作流程

3.1 前置条件检查

执行任何下载操作前，请确认：

1. 程序已安装：终端执行 yt-dlp --version，若返回版本号则就绪；否则需先安装（见 3.2）
2. FFmpeg 可用：音频提取和视频合并依赖 FFmpeg，执行 ffmpeg -version 验证
3. 网络连通：目标网站可正常访问
4. URL 有效：视频链接未失效、非私有内容

3.2 安装指引

# macOS (Homebrew)
brew install yt-dlp ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install yt-dlp ffmpeg

# Windows (Scoop)
scoop install yt-dlp ffmpeg

# Python 方式（通用）
python3 -m pip install -U yt-dlp

3.3 分步执行流程

步骤 1：确认输入

• 获取用户提供的 URL，检查是否为有效链接格式
• 询问下载偏好：画质要求、是否需要字幕、输出目录等

步骤 2：构造命令

根据需求组合参数，常用参数速查：

参数	作用	示例值
-f	指定格式	best, bv*+ba, bestvideo[height<=720]
-x	提取音频	无值
--audio-format	音频输出格式	mp3, m4a, flac
-o	输出文件名模板	%(title)s.%(ext)s
--write-subs	下载字幕	无值
--sub-langs	字幕语言	zh-Hans,en
-c	断点续传	无值
-r	限速	500K, 1M
-J	输出 JSON 元数据	无值
--cookies	指定 cookies 文件	cookies.txt
--proxy	使用代理	socks5://127.0.0.1:1080
--download-archive	记录已下载视频	archive.txt

步骤 3：执行命令

在终端运行构造好的命令，观察输出日志。

步骤 4：验证结果

• 检查输出文件是否存在且大小合理
• 音频文件用播放器试听；视频文件检查分辨率是否达标
• 若失败，参考第五节错误码表排查

3.4 输出规范

• 成功：返回文件路径、文件大小、格式信息
• 部分成功（批量场景）：列出成功项与失败项清单，失败项附原因
• 完全失败：返回错误码与修正建议

---

四、置信度门控机制

当遇到以下情况时，不得编造信息，必须输出 [需核实:字段] 占位符：

场景	输出示例
用户提供 URL 但未说明画质偏好	默认使用 best，但提示"已选最高画质，如需指定分辨率请说明"
不确定网站是否受支持	"该网站支持情况 [需核实:站点支持状态]，建议先执行 yt-dlp -F <URL> 查看可用格式"
下载失败原因不明	"错误码 [需核实:错误码含义]，请提供完整日志以便分析"
询问特定网站的私有 API 细节	"内部实现细节 [需核实:不公开信息]，建议查阅官方文档"

---

五、错误码体系

错误码/现象	可能原因	提示话术	修正步骤
ERROR: Unsupported URL	网站不受支持或链接格式错误	"该链接格式无法识别"	1. 确认 URL 完整；2. 用浏览器打开验证；3. 检查网站是否在支持列表
ERROR: Unable to extract video data	网站页面结构变更或需登录	"视频数据提取失败"	1. 更新 yt-dlp（yt-dlp -U）；2. 添加 --cookies 参数
ERROR: ffmpeg not found	FFmpeg 未安装或未加入 PATH	"缺少 FFmpeg 组件"	1. 安装 FFmpeg；2. 重启终端
ERROR: HTTP Error 403	服务器拒绝访问（反爬）	"访问被拒绝"	1. 添加 --user-agent 自定义 UA；2. 使用 --cookies 模拟浏览器
ERROR: unable to download video data	网络中断或限流	"下载中断"	1. 添加 -c 续传；2. 添加 -r 500K 限速重试
下载后文件损坏	磁盘空间不足或写入中断	"文件可能不完整"	1. 检查磁盘空间；2. 删除重下
音频转换失败	FFmpeg 编码器问题	"音频转换出错"	1. 更换 --audio-format 为 m4a；2. 更新 FFmpeg

---

六、FAQ 反模式对照

反模式 1：盲目使用最高画质

错误做法：直接 yt-dlp <URL> 下载，结果得到 4K 视频，文件巨大且播放卡顿。

正确姿势：先执行 yt-dlp -F <URL> 查看可用格式列表，再根据设备能力选择：

本技能来自小葱技能站7w4.net。

# 查看格式
yt-dlp -F <URL>
# 选择 1080p 且为 mp4 容器
yt-dlp -f "bv*[height<=1080][ext=mp4]+ba[ext=m4a]/b[height<=1080][ext=mp4]" <URL>

反模式 2：忽略播放列表递归

错误做法：用户给的是播放列表 URL，直接下载只得到第一个视频。

正确姿势：确认 URL 类型，播放列表需显式处理：

# 只下载列表中的前 5 个
yt-dlp --playlist-items 1-5 <playlist_url>
# 或只下载第 3 个
yt-dlp --playlist-items 3 <playlist_url>

反模式 3：不处理登录墙

错误做法：下载需要登录的视频，直接报错后放弃。

正确姿势：导出浏览器 cookies 后传入：

# 使用浏览器扩展导出 cookies.txt
yt-dlp --cookies cookies.txt <URL>

反模式 4：文件名冲突与特殊字符

错误做法：使用默认文件名，结果包含非法字符或重名覆盖。

正确姿势：自定义输出模板：

yt-dlp -o "%(channel)s/%(playlist_title)s/%(playlist_index)02d_%(title)s.%(ext)s" <URL>

反模式 5：忽略归档文件

错误做法：重复下载已获取的视频，浪费时间与带宽。

正确姿势：使用归档文件记录历史：

yt-dlp --download-archive downloaded.txt <URL>

---

七、渐进式披露路径

7.1 速查卡（30 秒上手）

# 下载视频（默认最高画质）
yt-dlp <URL>

# 提取音频为 mp3
yt-dlp -x --audio-format mp3 <URL>

# 批量下载播放列表
yt-dlp -f best <playlist_url>

# 查看视频信息
yt-dlp -J <URL>

7.2 新手进阶路径

第一阶段（基础操作）：掌握单视频下载、音频提取、格式选择。

第二阶段（批量处理）：学习播放列表控制、归档文件、输出模板定制。

第三阶段（高级定制）：编写配置文件（yt-dlp.conf）固化常用参数，使用 --match-filter 按标题/时长过滤，结合 --exec 在下载后自动执行脚本。

7.3 配置文件示例

创建 ~/.config/yt-dlp/config 文件：

# 默认输出路径
-o "%(title)s.%(ext)s"

# 默认下载字幕
--write-subs
--sub-langs zh-Hans,en

# 默认音频提取
-x
--audio-format mp3

# 断点续传
-c

# 归档
--download-archive ~/yt-dlp-archive.txt

---

八、高级技巧与参数详解

8.1 格式选择表达式

格式选择是 yt-dlp 最强大的功能之一，语法规则：

符号	含义	示例
+	合并（视频+音频）	bv*+ba
/	或（回退）	best/bestvideo
[]	属性过滤	[height<=1080]
*	任意数量	bv*（任意视频流）
best	最佳质量	best
worst	最差质量	worst

常用组合：

# 1080p 以内，优先 mp4
-f "bv*[height<=1080][ext=mp4]+ba[ext=m4a]/b[height<=1080][ext=mp4]"

# 只要视频不要音频（无声）
-f "bv"

# 最差画质（省流量）
-f "worst"

8.2 输出模板变量

变量	含义
%(title)s	视频标题
%(id)s	视频 ID
%(uploader)s	上传者
%(channel)s	频道名
%(upload_date)s	上传日期（YYYYMMDD）
%(playlist_title)s	播放列表标题
%(playlist_index)s	在列表中的序号
%(duration)s	时长（秒）
%(ext)s	文件扩展名

8.3 后处理操作

# 下载后自动嵌入缩略图
yt-dlp --embed-thumbnail <URL>

# 下载后自动嵌入元数据
yt-dlp --embed-metadata <URL>

# 下载后执行自定义脚本
yt-dlp --exec "echo %(title)s >> downloaded.log" <URL>

---

九、常见问题深度解析

9.1 下载速度慢

• 尝试添加 -r 0 取消限速（默认可能被服务器限制）
• 使用 --concurrent-fragments 4 增加并发分片数
• 更换网络环境或使用代理

9.2 视频与音频分离

部分网站（如 YouTube）的高画质视频和音频是分离的，需要合并：

# 自动合并（需 FFmpeg）
yt-dlp -f "bv*+ba" <URL>

9.3 仅下载部分片段

# 下载视频的第 10 到 20 秒
yt-dlp --download-sections "*10:00-20:00" <URL>

9.4 更新程序

# 自动更新到最新版
yt-dlp -U

---

十、用户协议

使用 yt-dlp Skill 即表示您同意以下条款：

1. 责任承担：使用者应自行承担因使用本 Skill 产生的全部责任。本 Skill 仅提供技术操作指导，不承担因下载内容引发的版权纠纷、法律诉讼或其他任何形式的责任。

2. 合法使用：使用者须确保下载行为符合当地法律法规及目标网站的服务器条款。禁止将本 Skill 用于侵犯他人知识产权、商业机密或个人隐私的用途。

3. 禁止反向工程：使用者不得对本 Skill 文档进行反向工程、反编译、破解或试图提取底层算法，除非适用法律明确允许。

4. 无担保声明：本 Skill 按"现状"提供，不附带任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权保证。

5. 内容免责：本 Skill 不存储、不托管、不传输任何媒体内容，仅提供命令行工具的使用方法说明。所有下载行为均由使用者主动发起。

---

十一、许可证（License）

MIT License

Copyright (c) 2026 LinguaForge Studio

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO

这是一个质量不错的视频下载工具，文档写得很详细，从简单下载到高级技巧都有覆盖，代码功能完整靠谱。不过文档里还残留着一些标记没清理干净，部分地方说得有点啰嗦。总体上推荐使用，但建议开发者再打磨一下文档的整洁度。