实用工具与效率技巧

yt-dlp 完全使用指南：从入门到精通的下载神器

🎯 什么是 yt-dlp？ {#什么是yt-dlp}

yt-dlp 是一个基于 Python 的命令行程序，用于从 YouTube 等上千个网站下载视频和音频。它是著名 youtube-dl 项目的加强版分支，相比原版具有：

🚀 更快的更新频率 - 及时适配网站变更
✨ 更多功能特性 - 支持多线程下载、格式筛选优化
🔧 更好的兼容性 - 修复了大量原版存在的问题
📦 丰富的后处理 - 内建格式转换、元数据嵌入等功能

目前支持超过 1500+ 个网站，包括 YouTube、Bilibili、Twitter、Instagram、TikTok 等主流平台。

📥 安装指南 {#安装指南}

Windows 安装

方法一：使用安装包（推荐新手）

访问 yt-dlp 发布页面
下载 yt-dlp.exe 文件
将文件放入系统 PATH 路径（如 C:\Windows）或任意文件夹并添加到环境变量

方法二：使用 Chocolatey

bash

choco install yt-dlp

方法三：使用 pip

bash

python -m pip install -U yt-dlp

macOS 安装

使用 Homebrew

bash

brew install yt-dlp

使用 pip

bash

python3 -m pip install -U yt-dlp

Linux 安装

Ubuntu/Debian

bash

sudo apt update
sudo apt install yt-dlp

使用 pip（推荐获取最新版）

bash

python3 -m pip install -U yt-dlp

下载二进制文件

bash

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 - 用于格式转换、视频合并
- Windows: 下载 ffmpeg 并添加到 PATH
- macOS: brew install ffmpeg
- Linux: sudo apt install ffmpeg

🚀 基础使用入门 {#基础使用入门}

最简单的下载

bash

# 直接下载最高画质视频
yt-dlp "视频URL"

# 下载整个播放列表
yt-dlp "播放列表URL"

常用基础选项

bash

# 指定输出文件名格式
yt-dlp -o "%(title)s.%(ext)s" "URL"

# 列出可下载的格式
yt-dlp -F "URL"

# 下载特定格式（如最佳画质+最佳音频）
yt-dlp -f "bestvideo+bestaudio" "URL"

# 下载为mp4格式
yt-dlp -f "best[ext=mp4]" "URL"

# 下载音频并转换为mp3
yt-dlp -x --audio-format mp3 "URL"

第一个实用命令

bash

# 下载YouTube视频为mp4，保存到指定目录
yt-dlp -f "best[ext=mp4]" -o "D:/Videos/%(title)s.%(ext)s" "https://www.youtube.com/watch?v=xxxxxx"

🔧 核心功能详解 {#核心功能详解}

输出模板（Output Template）

yt-dlp 支持灵活的命名规则，常用变量：

变量	说明	示例值
`%(title)s`	视频标题	我的视频
`%(id)s`	视频ID	abc123
`%(ext)s`	文件扩展名	mp4
`%(uploader)s`	上传者	张三
`%(playlist)s`	播放列表名	我的收藏
`%(playlist_index)s`	在列表中的序号	1

使用示例：

bash

# 按上传者/播放列表/序号-标题组织
yt-dlp -o "%(uploader)s/%(playlist)s/%(playlist_index)02d-%(title)s.%(ext)s" "URL"

# 添加日期信息
yt-dlp -o "%(upload_date)s-%(title)s.%(ext)s" "URL"

# 限制标题长度
yt-dlp -o "%(title).50s.%(ext)s" "URL"

下载限速与限流

bash

# 限制下载速度为 1MB/s
yt-dlp -r 1M "URL"

# 限制同时下载的连接数
yt-dlp --limit-rate 500k --concurrent-fragments 3 "URL"

断点续传与重试

bash

# 断点续传（默认启用）
yt-dlp --continue "URL"

# 设置重试次数
yt-dlp --retries 10 "URL"

# 片段重试次数
yt-dlp --fragment-retries 15 "URL"

代理设置

bash

# HTTP代理
yt-dlp --proxy "http://127.0.0.1:1080" "URL"

# SOCKS5代理
yt-dlp --proxy "socks5://127.0.0.1:1080" "URL"

🎬 格式选择与处理 {#格式选择与处理}

格式选择语法

bash

# 查看所有可用格式
yt-dlp -F "URL"

# 选择最佳视频+最佳音频
yt-dlp -f "bestvideo+bestaudio" "URL"

# 选择特定格式ID
yt-dlp -f "137+140" "URL"

# 选择最佳画质且包含中文字幕
yt-dlp -f "bestvideo[height<=1080]+bestaudio" --sub-lang zh-Hans "URL"

格式筛选条件

bash

# 选择1080p以内的最佳视频
yt-dlp -f "best[height<=1080]" "URL"

# 选择mp4格式且大于100MB的视频
yt-dlp -f "best[ext=mp4][filesize>100M]" "URL"

# 优先选择HDR视频
yt-dlp -f "bestvideo[vcodec*=hdr]" "URL"

音频提取与转换

bash

# 提取音频为最佳质量
yt-dlp -x "URL"

# 提取并转换为mp3
yt-dlp -x --audio-format mp3 --audio-quality 0 "URL"

# 提取并保持原音频格式
yt-dlp -x --audio-format best "URL"

# 下载特定音轨（如多语言视频）
yt-dlp -f "bestaudio[language=zh]" "URL"

字幕下载

bash

# 下载所有字幕
yt-dlp --write-subs "URL"

# 下载自动生成字幕
yt-dlp --write-auto-subs "URL"

# 指定字幕语言
yt-dlp --write-subs --sub-lang "zh-Hans,en" "URL"

# 下载字幕并嵌入视频
yt-dlp --write-subs --embed-subs "URL"

缩略图与元数据

bash

# 下载缩略图
yt-dlp --write-thumbnail "URL"

# 嵌入缩略图到文件
yt-dlp --embed-thumbnail "URL"

# 写入元数据
yt-dlp --add-metadata --metadata-from-title "%(title)s" "URL"

# 嵌入章节信息
yt-dlp --embed-chapters "URL"

🔥 高级应用技巧 {#高级应用技巧}

多线程下载

bash

# 使用多线程下载片段（YouTube DASH视频）
yt-dlp --concurrent-fragments 5 "URL"

# 同时下载多个视频（需配合外部工具）
yt-dlp --batch-file urls.txt --concurrent-fragments 3

批量下载与列表处理

bash

# 从文件读取URL列表
yt-dlp -a urls.txt

# 下载频道所有视频
yt-dlp "https://www.youtube.com/@channelname"

# 下载指定日期范围内的视频
yt-dlp --dateafter 20230101 --datebefore 20231231 "频道URL"

# 下载热门视频
yt-dlp --playlist-start 1 --playlist-end 50 "URL"

bash

# 从浏览器导入cookies
yt-dlp --cookies-from-browser chrome "URL"

# 使用cookies文件
yt-dlp --cookies cookies.txt "URL"

# 使用用户名密码（不推荐，除非必要）
yt-dlp --username yourname --password yourpass "URL"

自定义请求头

bash

# 设置User-Agent
yt-dlp --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." "URL"

# 添加Referer
yt-dlp --add-header "Referer:https://example.com" "URL"

后处理脚本

bash

# 下载后执行自定义脚本
yt-dlp --exec "echo %(filepath)s downloaded" "URL"

# 重命名文件
yt-dlp --exec "mv {} /target/directory/" "URL"

# 下载后自动播放
yt-dlp --exec "vlc {}" "URL"

⚙️ 配置文件与自动化 {#配置文件与自动化}

全局配置文件

Windows路径：

%APPDATA%\yt-dlp\config.txt
C:\Users\用户名\yt-dlp.conf

Linux/macOS路径：

/etc/yt-dlp.conf
~/.config/yt-dlp/config
~/.yt-dlp/config

配置文件示例

ini

# 默认输出模板
-o ~/Videos/%(uploader)s/%(title)s.%(ext)s

# 默认下载最佳画质
-f bestvideo+bestaudio/best

# 合并时使用mp4容器
--merge-output-format mp4

# 写入字幕和元数据
--write-subs
--write-auto-subs
--sub-lang zh-Hans,en
--embed-subs
--add-metadata
--embed-thumbnail

# 下载限速
--limit-rate 5M

# 代理设置
--proxy http://127.0.0.1:7890

# 缓存目录
--cache-dir ~/.cache/yt-dlp

使用项目特定配置

bash

# 为当前目录创建配置
echo "-f best" > ./yt-dlp.conf

# 指定配置文件
yt-dlp --config-location ./myconfig.conf "URL"

定时下载脚本示例

Linux crontab 示例：

bash

# 每天凌晨3点下载指定播放列表
0 3 * * * /usr/local/bin/yt-dlp "https://youtube.com/playlist?list=xxx" -o "/home/user/videos/%%(title)s.%%(ext)s"

Windows 任务计划程序：

powershell

# PowerShell 脚本示例
$urls = @(
    "https://youtube.com/watch?v=xxx",
    "https://bilibili.com/video/xxx"
)
foreach ($url in $urls) {
    yt-dlp -f best -o "D:\Videos\%(title)s.%(ext)s" $url
}

🔍 常见问题排查 {#常见问题排查}

更新问题

bash

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

# 使用 pip 更新
pip install -U yt-dlp

# 如果网站无法下载，可能是版本过旧
yt-dlp --version

下载失败处理

bash

# 启用详细输出排查问题
yt-dlp --verbose "URL"

# 忽略错误继续下载列表
yt-dlp --ignore-errors "播放列表URL"

# 跳过不可用视频
yt-dlp --skip-unavailable-fragments "URL"

合并失败问题

bash

# 指定 ffmpeg 路径
yt-dlp --ffmpeg-location /usr/bin/ffmpeg "URL"

# 不合并直接下载
yt-dlp -f best --no-mux "URL"

# 下载后手动合并
ffmpeg -i video.mp4 -i audio.m4a -c copy output.mp4

提取信息失败

bash

# 清除缓存
yt-dlp --rm-cache-dir

# 使用不同提取器
yt-dlp --extractor-retries 10 "URL"

# 指定提取器
yt-dlp --force-generic-extractor "URL"

常见错误代码

错误	可能原因	解决方法
ERROR: Unsupported URL	不支持该网站	更新 yt-dlp，或使用通用提取器
HTTP Error 403	访问被拒绝	添加 cookies 或 user-agent
ffmpeg not found	缺少合并工具	安装 ffmpeg 并添加到 PATH
Requested format not available	格式不可用	检查 -F 查看可用格式
Video unavailable	视频已删除	检查 URL 是否正确

💡 实用命令示例 {#实用命令示例}

YouTube 下载精选

bash

# 下载最高画质视频+音频，嵌入字幕和缩略图
yt-dlp -f "bestvideo+bestaudio" --merge-output-format mp4 \
  --write-subs --sub-lang zh-Hans --embed-subs \
  --write-thumbnail --embed-thumbnail \
  --add-metadata \
  -o "%(uploader)s/%(title)s.%(ext)s" "URL"

# 下载 YouTube 播放列表为 MP3
yt-dlp -x --audio-format mp3 --audio-quality 0 \
  --embed-thumbnail --add-metadata \
  -o "%(playlist)s/%(playlist_index)02d-%(title)s.%(ext)s" "播放列表URL"

# 下载 YouTube 频道最近一周的视频
yt-dlp --dateafter $(date -d "7 days ago" +%Y%m%d) "频道URL"

Bilibili 下载

bash

# 下载 B站视频（自动选择最佳画质）
yt-dlp "https://www.bilibili.com/video/BV1xx411c7mD"

# 下载 B站合集/列表
yt-dlp "https://www.bilibili.com/medialist/play/xxx"

# 下载弹幕
yt-dlp --write-subs --sub-lang zh-Hans "B站URL"

社交媒体下载

bash

# 下载 Twitter 视频
yt-dlp "https://twitter.com/user/status/123456789"

# 下载 Instagram 帖子
yt-dlp "https://www.instagram.com/p/xxxxx/"

# 下载 TikTok 无水印
yt-dlp "https://www.tiktok.com/@user/video/123456"

音乐/播客下载

bash

# 下载 SoundCloud 歌单为 MP3
yt-dlp -x --audio-format mp3 --embed-thumbnail \
  --add-metadata -o "%(playlist)s/%(track_number)d-%(title)s.%(ext)s" "歌单URL"

# 下载播客并添加章节标记
yt-dlp -x --audio-format m4a --embed-chapters "播客URL"

高级定制命令

bash

# 下载视频并自动发送到 Telegram
yt-dlp "URL" --exec "python send_to_telegram.py {}"

# 按日期组织下载，并创建播放列表文件
yt-dlp -o "%(upload_date)s/%(title)s.%(ext)s" --write-info-json "URL"

# 下载1080p视频，如果不存在则降级
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best" "URL"

📖 总结与资源 {#总结与资源}

核心命令速查表

功能	命令
查看格式	`yt-dlp -F URL`
最佳画质	`yt-dlp -f "bestvideo+bestaudio" URL`
下载MP3	`yt-dlp -x --audio-format mp3 URL`
下载字幕	`yt-dlp --write-subs --sub-lang zh-Hans URL`
批量下载	`yt-dlp -a urls.txt`
使用配置	`yt-dlp --config-location config.conf URL`
更新	`yt-dlp -U`

学习资源

官方文档: yt-dlp GitHub Wiki
支持的网站列表: 支持网站
常见问题: FAQ
社区讨论: Discord

注意事项

尊重版权 - 只下载有权下载的内容
遵守服务条款 - 某些网站禁止爬取
合理使用 - 避免对目标服务器造成过大压力
隐私保护 - 注意 cookies 文件中的敏感信息

最后更新

本文档基于 yt-dlp 2024.01.02 版本。由于变更频繁，建议定期更新 yt-dlp 以获取最佳兼容性。

祝你使用愉快！如果有任何问题，欢迎在评论区留言讨论。 🎉

如果觉得文章对你有用，请随意赞赏

音视频处理教程开源软件命令行工具视频下载 yt-dlp

yt-dlp 完全使用指南：从入门到精通的下载神器

https://niujinkai.com/archives/yt-dlp-download.html

作者

哦吼

发布于

2024年01月01日

更新于

2026年02月25日

许可协议

CC BY 4.0

yt-dlp 完全使用指南：从入门到精通的下载神器

🎯 什么是 yt-dlp？ {#什么是yt-dlp}

📥 安装指南 {#安装指南}

Windows 安装

macOS 安装

Linux 安装

可选依赖安装

🚀 基础使用入门 {#基础使用入门}

最简单的下载

常用基础选项

第一个实用命令

🔧 核心功能详解 {#核心功能详解}

输出模板（Output Template）

下载限速与限流

断点续传与重试

代理设置

🎬 格式选择与处理 {#格式选择与处理}

格式选择语法

格式筛选条件

音频提取与转换

字幕下载

缩略图与元数据

🔥 高级应用技巧 {#高级应用技巧}

多线程下载

批量下载与列表处理

Cookie 与登录

自定义请求头

后处理脚本

⚙️ 配置文件与自动化 {#配置文件与自动化}

全局配置文件

配置文件示例

使用项目特定配置

定时下载脚本示例

🔍 常见问题排查 {#常见问题排查}

更新问题

下载失败处理

合并失败问题

提取信息失败

常见错误代码

💡 实用命令示例 {#实用命令示例}

YouTube 下载精选

Bilibili 下载

社交媒体下载

音乐/播客下载

高级定制命令

📖 总结与资源 {#总结与资源}

核心命令速查表

学习资源

注意事项

最后更新

作者

发布于

更新于

许可协议

评论