yt-dlp 错误全解：每个错误的含义与真正有效的修复

作者 Tunelio 团队·发布于 2026年9月7日

yt-dlp 在 YouTube 上几乎所有失败都源于三件事之一：构建过旧、缺少 JavaScript 运行时，或 YouTube 不信任的 IP 地址。先运行下面三条命令，它们能解决大多数报告。然后在目录里找到你的确切错误信息 —— 每一条都给出原因、第一步尝试，以及该错误的完整指南。

通用急救（先做这个）

yt-dlp -U                                   # 或：pip install -U yt-dlp   （发行版软件包落后数月）
curl -fsSL https://deno.land/install.sh | sh  # JS 运行时 —— 2025 年起 YouTube 必需
yt-dlp -4 --rm-cache-dir -vU "URL"             # IPv4、清空缓存、详细输出：看它在哪里失败

从上到下读 -v 输出：调试头部显示版本、找到的 JS 运行时和 ffmpeg；第一个 WARNING 或 ERROR 告诉你哪个阶段失败 —— 信息请求（YouTube 不肯描述视频）、媒体下载（描述了但拒绝给文件），或后处理（ffmpeg）。下面的目录就是这样分组的。

信息阶段错误：YouTube 不愿和你对话

“Sign in to confirm you’re not a bot”

YouTube 把你的请求判为自动化 —— 数据中心或 IPv6 地址、没有 PO token、没有会话、请求量过大。修复顺序：更新、JS 运行时、-4，然后是隐私窗口中备用账号的 cookies，再是 PO token provider，最后是住宅出口。单靠 cookies 撑不久。

→ 完整指南：修复 “Sign in to confirm you’re not a bot”

“Unable to extract …”、“nsig extraction failed”、“Some formats may be missing”

YouTube 更改了播放器代码，你的 yt-dlp 无法解出新签名，或者没有 JavaScript 运行时来执行它。更新（稳定版未发布就用 nightly）并安装 Deno；如果装过过时的 YTNsigDeno 插件请卸载。旧构建上没有任何参数能修复这个问题。

→ 完整指南：如何更新 yt-dlp

“Video unavailable”、“Private video”、“HTTP Error 404: Not Found”

视频已删除、私密、受地区或会员限制 —— 或者 ID 打错了。在浏览器中检查 URL：那里也失败的话，yt-dlp 里什么都帮不上。下载途中的 404 则意味着签名媒体 URL 过期（用 -c 重新提取）；播放列表中加 --ignore-errors 跳过失效条目。

→ 完整指南：HTTP Error 404 的原因与修复

“Cookies are no longer valid”、“could not find … cookies database”、年龄限制 / 仅会员

会话 cookies 会轮换和过期；从你持续使用的浏览器导出的文件立刻就是陈旧的，而主账号的 cookies 可能让账号被限制。从备用账号的隐私窗口导出一次，关闭窗口，传入 --cookies cookies.txt。年龄限制和仅会员视频需要能看到它们的账号的 cookies。

→ 完整指南：安全地导出与使用 cookies

媒体阶段错误：YouTube 描述了视频却拒绝给文件

“HTTP Error 403: Forbidden”（常在第一块之后）

签名媒体 URL 与 YouTube 预期的客户端、IP 或 PO token 不匹配。更新并安装 JS 运行时，强制 IPv4，停止用 -f 强制 itag（改用 -S 排序），尝试另一个播放器客户端，提供 PO token；cookies 放最后 —— 它们可能造成媒体 403。数据中心和 IPv6 地址遇到这个的频率高得多。

→ 完整指南：403 Forbidden 的原因与修复顺序

“Requested format is not available”

你强制的 itag 在这个视频上不存在，或对你的客户端被 PO token 门控。用 -F 列出格式，然后表达偏好而不是指定 ID：-S "res:1080,ext:mp4"。如果 1080p 以上完全缺失，原因是 ffmpeg（用于合并）或 PO token。

→ 完整指南：ffmpeg、合并，以及为什么缺 1080p

下载极慢（每秒几 KB）、卡住、限速

限速是 YouTube 对错误 “n” 参数的回应 —— 几乎总是构建过旧或缺少 JS 运行时，不是你的网络。先更新；然后 --concurrent-fragments 4 对分片格式有帮助。批量运行时的速率限制是另一回事：加 sleep 参数。

→ 完整指南：更新 yt-dlp

代理错误：“Unable to connect to proxy”、“Missing dependencies for SOCKS support”、经代理仍被机器人验证

检查协议和端口（远程 DNS 用 socks5h://），为 SOCKS 安装 yt-dlp[default]，并记住出口的信誉和你服务器的一样被打分 —— 数据中心代理继承同样的 403 和机器人验证；住宅出口有效，但整段视频都要经过它们。

→ 完整指南：对 YouTube 真正有效的代理

后处理错误：ffmpeg

“ffmpeg not found”、“You have requested merging … but ffmpeg is not installed”

没有 ffmpeg，yt-dlp 会悄悄保存最佳单文件格式（通常 720p），也做不出 MP3。安装它（apt/brew/winget），打开新终端，或传入 --ffmpeg-location。在 yt-dlp -v 里检查 ffmpeg 那一行。

→ 完整指南：安装 ffmpeg 并让 yt-dlp 找到它

“Postprocessing: Conversion failed!”、输出是 .webm 而不是 .mp3

损坏的部分下载、非常旧的 ffmpeg，或根本没有 ffmpeg。删除 .part 文件，更新两个工具，用 -x --audio-format mp3 --audio-quality 0 重试 —— 或用 --audio-format best 保留原始 Opus/AAC，跳过转码。

→ 完整指南：yt-dlp 转 MP3

→ 该保留哪个：WebM/Opus、M4A 还是 MP3

代码中的错误：Python 的 DownloadError、卡死的异步服务器

yt-dlp 把失败包在 yt_dlp.utils.DownloadError 里，原始信息在其中 —— 按文本匹配（“Sign in to confirm”、“HTTP Error 403”、“Private video”）。它是同步的，每次提取约耗 1.2 秒 CPU；在事件循环上调用会冻结服务器 —— 请在线程池中运行并限制并发。

→ 完整指南：从 Python 使用 yt-dlp

→ 把 yt-dlp 放到 API 后面：自建还是托管

运行它安全吗、合法吗？

yt-dlp 本身开源，从官方发布或 pip 安装是安全的；Windows 构建上的杀毒标记是 PyInstaller 误报。风险在于假下载站、主账号的 cookies 和不受信任的插件。合法性取决于你下载什么以及身在何处。

→ 完整指南：yt-dlp 安全吗？

把一个错误变成永久错误的做法

• 在紧密循环中重试机器人验证或 403 —— 让 IP 被永久标记的最快方式。
• 在服务器上传入个人 Google 账号的 cookies。
• 照搬旧教程强制 itag（-f 137+140）而不是 -S 排序。
• 还在用去年的发行版软件包，读论坛而不是更新。
• 轮换廉价数据中心代理并指望得到不同的信誉。

什么时候该停止修 yt-dlp

对少量个人下载，急救命令和上面的指南就够了。如果 yt-dlp 运行在机器人、应用或流水线里，上面的每个错误都会变成反复的运维任务 —— 更新、运行时、PO token、cookie 轮换、住宅代理、ffmpeg CPU。托管 API 对每个请求返回下载 URL，并把这一切留在服务端。Tunelio 是我们自己的服务，请自行权衡。新账号可获得 100 个免费额度。

→ yt-dlp 替代方案：何时该用托管 API

来源

• yt-dlp README 与 wiki —— 选项参考、FAQ、PO token 指南、cookies 指南。
• yt-dlp issue 跟踪 —— #14680 与 #17395（403）、机器人验证与 nsig 讨论。
• 我们自己的测量（Tunelio 提取集群，2026）：数据中心 IP 的挑战率、IPv6 拒绝、每次提取的 CPU。