问题排查
常见错误
yt-dlp 常见错误信息及解决方案
HTTP 403 Forbidden
ERROR: unable to download video data: HTTP Error 403: Forbidden原因：网站拒绝了请求，可能是需要认证、反爬策略或地区限制。
解决方案：
# 1. 更新 yt-dlp
yt-dlp -U
# 2. 使用 Cookies
yt-dlp --cookies-from-browser chrome "URL"
# 3. 使用代理
yt-dlp --proxy "http://127.0.0.1:7890" "URL""Sign in to confirm your age"
ERROR: Sign in to confirm your age. This video may be inappropriate for some users.解决方案：使用已登录的浏览器 Cookies。
yt-dlp --cookies-from-browser chrome "URL""Video unavailable"
ERROR: Video unavailable. This video is not available in your country.解决方案：
# 使用对应国家的代理
yt-dlp --proxy "socks5://proxy:port" "URL"
# 或开启地理限制绕过
yt-dlp --geo-bypass "URL""Unable to extract" 错误
ERROR: [bilibili] Unable to extract ...原因：yt-dlp 版本过旧，网站结构已更新。
# 更新到最新版
yt-dlp -U
pip install -U yt-dlpFFmpeg 未找到
ERROR: ffmpeg not found. Please install ffmpeg.
WARNING: Requested formats are incompatible for merge and will be merged into mkv.解决方案：安装 FFmpeg，参见 FFmpeg 安装指南。
下载速度极慢
可能原因：
- 网站限速
- DNS 解析问题
- 代理配置错误
# 使用并发下载
yt-dlp -N 4 "URL"
# 检查代理
yt-dlp --proxy "" "URL" # 清除代理
# 指定 DNS
# (需要在系统层面配置)SSL 证书错误
ERROR: Unable to download webpage: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED]># 临时方案（不推荐用于生产环境）
yt-dlp --no-check-certificates "URL"--no-check-certificates 会跳过 SSL 验证，可能存在安全风险。建议修复系统的
SSL 证书配置。
"Incomplete data received"
ERROR: unable to download video data: <urlopen error Incomplete data received># 重试 + 断点续传
yt-dlp -c --retries 10 --fragment-retries 10 "URL"文件名过长
ERROR: [Errno 36] File name too long# 截断文件名
yt-dlp -o "%(title).100s.%(ext)s" "URL"
# 或使用 ID 作为文件名
yt-dlp -o "%(id)s.%(ext)s" "URL"
# 限制为 Windows 兼容文件名
yt-dlp --windows-filenames "URL"合并失败
ERROR: Postprocessing: Merging formats...failed# 确认 FFmpeg 版本
ffmpeg -version
# 指定兼容格式避免合并
yt-dlp -f "best[ext=mp4]" "URL"
# 或指定合并格式
yt-dlp --merge-output-format mkv "URL"调试技巧
# 详细输出模式，看到所有请求和响应
yt-dlp -v "URL"
# 只打印信息不下载
yt-dlp -j "URL" | python -m json.tool
# 打印提取器信息
yt-dlp --print extractor "URL"