yt-dlp-downloader

yt-dlp 视频下载器

使用 yt-dlp 下载数千个网站上的视频。

前置条件

下载前，请确认已安装依赖项：

# Check yt-dlp
which yt-dlp || echo "yt-dlp not installed. Install with: pip install yt-dlp"

# Check ffmpeg (required for audio extraction and format merging)
which ffmpeg || echo "ffmpeg not installed. Install with: brew install ffmpeg"

如果尚未安装，请先安装：

pip install yt-dlp
brew install ffmpeg  # macOS

快速开始

基本下载（最佳画质）

yt-dlp -P "~/Downloads/yt-dlp" "VIDEO_URL"

下载 YouTube 视频（推荐 - 使用 Cookie）

YouTube 经常会通过 403 错误阻止直接下载。下载 YouTube 视频时，请始终使用浏览器 Cookie：

yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "YOUTUBE_URL"

支持的浏览器：chrome、firefox、safari、edge、brave、opera

使用自定义输出路径下载

yt-dlp -P "/path/to/save" -o "%(title)s.%(ext)s" "VIDEO_URL"

常见任务

1. 下载视频（默认 - 最佳画质）

yt-dlp -P "~/Downloads/yt-dlp" "VIDEO_URL"

2. 仅提取音频（MP3）

yt-dlp -P "~/Downloads/yt-dlp" -x --audio-format mp3 "VIDEO_URL"

3. 下载字幕

yt-dlp -P "~/Downloads/yt-dlp" --write-subs --sub-langs all "VIDEO_URL"

4. 下载指定画质

720p：

yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo[height<=720]+bestaudio/best[height<=720]" "VIDEO_URL"

1080p：

yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" "VIDEO_URL"

最佳可用画质：

yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo+bestaudio/best" "VIDEO_URL"

5. 列出可用格式（下载前）

yt-dlp -F "VIDEO_URL"

然后按 ID 下载指定格式：

yt-dlp -P "~/Downloads/yt-dlp" -f FORMAT_ID "VIDEO_URL"

6. 下载播放列表

# Download entire playlist
yt-dlp -P "~/Downloads/yt-dlp" -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "PLAYLIST_URL"

# Download specific range (e.g., items 1-5)
yt-dlp -P "~/Downloads/yt-dlp" -I 1:5 "PLAYLIST_URL"

7. 下载视频及缩略图

yt-dlp -P "~/Downloads/yt-dlp" --write-thumbnail "VIDEO_URL"

工作流

用户提供视频 URL 时：

1. 识别平台：

   • YouTube/YouTube Music → 始终使用 --cookies-from-browser chrome
   • 其他网站 → 先尝试不使用 Cookie

2. 询问用户的需求（如果未说明）：

   • 只下载视频？
   • 仅提取音频？
   • 需要字幕吗？
   • 指定画质？

3. 根据需求构建命令

4. 使用 Shell 工具执行下载，并设置 required_permissions: ["all", "network"]

5. 处理错误：

   • 403 Forbidden → 使用 --cookies-from-browser 重试
   • 连接问题 → yt-dlp 会自动续传，直接重试即可
   • 格式不可用 → 使用 -F 列出格式，然后选择

6. 报告结果 - 文件位置及任何错误

交互示例

用户：“帮我下载这个视频 https://www.youtube.com/watch?v=xxx”

回复：

# YouTube - use cookies to avoid 403 errors
yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "https://www.youtube.com/watch?v=xxx"

用户：“下载这个视频的音频 https://www.bilibili.com/video/xxx”

回复：

# Bilibili - extracting audio as MP3
yt-dlp -P "~/Downloads/yt-dlp" -x --audio-format mp3 "https://www.bilibili.com/video/xxx"

用户：“下载这个 Twitter 视频 https://twitter.com/xxx/status/123”

回复：

# Twitter/X - direct download usually works
yt-dlp -P "~/Downloads/yt-dlp" "https://twitter.com/xxx/status/123"

支持的网站

yt-dlp 支持数千个网站，包括：

• YouTube、YouTube Music
• Bilibili（B 站）
• Twitter/X
• TikTok、Douyin（抖音）
• Vimeo
• Twitch
• 以及更多网站……

完整列表：https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md

故障排除

常见错误及解决方案

错误	原因	解决方案
HTTP 403 Forbidden	YouTube 会阻止未经身份验证的请求	使用 --cookies-from-browser chrome
视频不可用	有地域限制或视频为私有	使用 Cookie 或 VPN
下载中断	网络问题	重试 - yt-dlp 会自动续传
格式不可用	请求的格式不存在	使用 -F 列出格式

错误：“yt-dlp: command not found”

pip install yt-dlp

错误：“ffmpeg not found”（用于提取音频）

brew install ffmpeg  # macOS

错误：HTTP 403 Forbidden（YouTube）

这是 YouTube 最常见的错误。下载 YouTube 视频时，请始终使用 Cookie：

# Recommended approach for YouTube
yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "YOUTUBE_URL"

支持的浏览器：chrome、firefox、safari、edge、brave、opera

错误：视频不可用或有地域限制

# Try with cookies from browser
yt-dlp --cookies-from-browser chrome "VIDEO_URL"

# Or use a specific format
yt-dlp -F "VIDEO_URL"  # List formats first
yt-dlp -f FORMAT_ID "VIDEO_URL"

错误：下载持续失败

# Update yt-dlp to latest version
pip install -U yt-dlp

# Force IPv4 (sometimes helps with connection issues)
yt-dlp -4 "VIDEO_URL"

最佳实践

1. 下载 YouTube 视频：始终使用 --cookies-from-browser chrome
2. 大文件：yt-dlp 会自动续传，中断时直接重试即可
3. 保持 yt-dlp 为最新版本：pip install -U yt-dlp
4. 先检查格式：如果不确定，下载前使用 -F