yt-dlp：支持数千网站的命令行音视频下载器部署指南

yt-dlp 是一个功能丰富的命令行音视频下载器，支持数千个网站。它是 youtube-dl 的分支，基于已停止维护的 youtube-dlc 发展而来。相比原版，yt-dlp 迭代更活跃、补丁更及时，支持更多站点和更细的格式选择，是目前最受欢迎的命令行下载工具之一。

它不只是"把视频下下来"：你可以精确选择画质与编码格式、只下音频、下载字幕、按时间区间裁剪、批量下载播放列表、抽取元数据、模拟浏览器 impersonation 绕过反爬，还能通过插件和配置文件把它串进自己的自动化管线。它以命令行和参数为核心，适合脚本化、批处理和服务器端使用。

一、项目官方信息

二、项目背景

在线视频网站普遍不提供"一键下载原片"的按钮，且不同站点的画质、编码、鉴权方式各不相同。原版 youtube-dl 维护放缓后，很多站点解析失效、补丁长期不合并。yt-dlp 接手后保持高频更新，把社区急需的修复、新站点支持、格式选择器增强都合进主干，迅速成为事实上的继任者。

它的设计哲学是"给你足够细的控制权"：网页上一个播放按钮背后，其实是多个音视频流的组合——视频流和音频流往往分开存储，需要用 ffmpeg 合并。yt-dlp 让你用 -f 参数精确指定要哪个视频流、哪个音频流，甚至只抽音频转 MP3。对做自媒体、视频归档、教学资料下载的人来说，这种颗粒度正是浏览器插件给不了的。

举个典型场景：你想把一个长篇讲座录下来离线听。用浏览器插件往往只能拿到默认画质、还带水印或广告；用 yt-dlp 一条命令就能只抽音频转成 MP3，按讲座标题命名，顺手把字幕也下下来。再比如你要归档一个教程频道，把频道根链接交给它，它会按播放列表结构整理成文件夹，整批下完。这种"可脚本化、可批处理、可精细控制"的能力，让它在服务器端归档、自媒体素材库、学术视频留存等场景里被广泛使用。

三、核心特性

• 数千站点支持：从 YouTube、B 站到各类新闻、播客、视频站，站点列表持续更新。
• 精细格式选择：用 -f 选择画质、编码，或用 -F 列出所有可用格式。
• 仅音频：-x 抽取音频并转码，配合 ffmpeg 转 MP3/M4A。
• 字幕与元数据：下载自动字幕、生成字幕文件，抽取视频标题、描述、缩略图。
• 播放列表批量：直接传播放列表或频道链接，整批下载。
• 时间区间裁剪：可只下载视频的某一段。
• 反爬与 impersonation：模拟浏览器指纹应对站点的反爬。
• 插件系统：支持安装第三方插件扩展站点与功能。
• 可配置：用配置文件固化常用参数，避免每次敲一长串命令。
• 活跃更新：站点变化快，版本以日期命名，建议保持最新。

这些能力组合起来，基本覆盖了"下载一个视频"之外的完整需求清单：选格式、抽音频、下字幕、存元数据、批量、裁剪、绕反爬、可扩展插件。它不提供图形界面，一切通过命令行参数表达，这既是缺点（新手要记参数），也是优点（可以写进 shell 脚本、cron 任务、自动化流水线）。配合配置文件，常用参数固化后，日常使用往往就是一条 yt-dlp 链接。

四、环境要求

• Python 3.9+：用 pip 安装时需要；用独立可执行文件则无需 Python。
• ffmpeg（强烈推荐）：合并音视频流、抽取音频转码、裁剪都依赖它；官方提供自己的构建 yt-dlp/FFmpeg-Builds。
• 网络：部分站点需要能正常访问；涉及登录内容时需提供 cookie。
• 版本时效：运行超过 90 天的版本会提示更新，因为站点解析随时可能失效。

五、部署步骤

方式一：pip 安装（推荐）

python -m pip install -U "yt-dlp[default]"

升级时重跑同一条命令即可。想装预发布的 nightly：

python -m pip install -U --pre "yt-dlp[default]"

方式二：独立可执行文件

从 Releases 下载对应平台的二进制（Windows 的 .exe、Linux/macOS 的独立可执行文件），放到 PATH 即可。用可执行文件安装的，可用 yt-dlp -U 自更新。切换更新通道：

yt-dlp --update-to nightly          # 从稳定版切到 nightly
yt-dlp --update-to stable@2023.07.06   # 指定版本

方式三：浏览器/服务器端批量使用

yt-dlp 本身是命令行工具，但常被部署在服务器上做批量归档：把它和 ffmpeg 一起装进 Docker，用一条命令把整个播放列表或频道拉下来。典型用法是：

# 列出所有可用格式
yt-dlp -F "https://www.youtube.com/watch?v=xxxx"

# 下载最佳画质（自动合并音视频）
yt-dlp "https://www.youtube.com/watch?v=xxxx"

# 只下载最佳音频并转成 mp3
yt-dlp -x --audio-format mp3 "https://www.youtube.com/watch?v=xxxx"

# 下载整个播放列表
yt-dlp -o "%(playlist_title)s/%(title)s.%(ext)s" "https://www.youtube.com/playlist?list=xxxx"

六、使用方法

最常用的几个参数：-F 列出格式、-f 选择格式（如 -f bestvideo+bestaudio 表示最佳视频流加最佳音频流，再由 ffmpeg 合并）、-x 只抽音频、--write-subs 下字幕、--cookies 传入 cookie 文件处理登录内容。输出文件名用 -o 加模板，比如 %(title)s.%(ext)s 用视频标题命名。

做批量下载时，建议先 -F 看一眼目标站点有哪些格式，再写死 -f 参数，避免每次都自动选最费时的最佳流。需要长期固定的参数写进配置文件，命令行就简洁了。遇到站点解析报错，先 yt-dlp -U 升级到最新版——绝大多数"突然下不了"都是站点改版导致，新版已修。

关于 ffmpeg 的角色要多说一句：它是 yt-dlp 最重要的外部依赖。没有 ffmpeg，你能下到单个流，但没法把视频流和音频流合并成一个完整文件，也没法把音频转成 MP3。官方维护的 yt-dlp/FFmpeg-Builds 提供了适配好的构建，装好后放在 PATH 里，yt-dlp 会自动调用。Linux 上也可以直接用发行版自带的 ffmpeg；macOS 用 Homebrew 装 ffmpeg；Windows 则下载官方构建并把 bin 目录加入 PATH。

几个进阶用法值得一提：--get-title、--get-url 可以不下载只取信息，适合先探测；--download-sections 能按时间区间只裁一段视频，长视频里只要某几分钟时很方便；--write-subs --sub-langs zh 只下中文字幕；--embed-thumbnail 把封面嵌进音频文件；-a urls.txt 从文件读一批链接批量下载。在服务器上做定时归档时，常把这些参数写进配置文件，再用 cron 定期拉新内容。

七、常见问题 FAQ

Q：下下来的视频只有画面没声音？ A：因为该站点把音视频分开存成两个流，需要 ffmpeg 合并。装好 ffmpeg 后 yt-dlp 会自动合并；没装 ffmpeg 就只能拿到其中一个流。

Q：提示某个站点解析失败怎么办？ A：先升级到最新版 yt-dlp -U 或 pip install -U yt-dlp，站点改版很频繁，新版通常已修；仍不行再去 issue 区反馈。

Q：能下载需要登录的视频吗？ A：可以，用 --cookies 传入从浏览器导出的 cookie 文件即可，但请确保你有权下载该内容。

Q：怎么只下音频？ A：用 -x --audio-format mp3（或 m4a），它会下载最佳音频流并用 ffmpeg 转码。

Q：许可证上有什么注意事项？ A：源码是 Unlicense（公共领域），但打包的可执行文件含 GPLv3+ 代码，整体按 GPLv3+ 发布；分发二进制时注意这一点。

Q：B 站这类国内站点支持吗？ A：支持数千站点，具体见 supportedsites.md，大部分主流视频站都在列。

Q：下载速度慢怎么办？ A：可以用 -N 加大并行分片数，或检查网络；部分站点对单连接限速，分片下载能提速。也可以通过 --downloader 指定不同的下载后端。

Q：它和浏览器里的下载插件什么关系？ A：插件面向普通用户、图形界面操作；yt-dlp 面向脚本与批量场景，参数更全、可控性更强、可服务器端无人值守运行。两者互补。

局限与注意

它只负责下载，不提供解码和绕 DRM 的能力；受版权保护或有 DRM 的内容无法处理。站点改版会临时导致某类下载失败，升级到最新版通常能修复。批量下载大文件时注意目标站点的访问频率，必要时加限速 -r 和间隔 --sleep-interval。下载会员内容要自备登录态 cookies，不要传播他人版权视频。

常用参数速记

记几个高频参数能覆盖大部分日常需求：-f bestvideo+bestaudio 选最佳画质并合并，-x --audio-format mp3 直接抽音频，--write-subs --sub-langs all 下载字幕，--download-archive done.txt 记录已下避免重复，-a list.txt 批量下清单里的链接，--cookies cookies.txt 登录态下载会员或年龄限制内容。配合配置文件把默认项固定下来，日常就只需给一个链接。

批处理与归档

对整个频道或播放列表，加 --flat-playlist 先看列表，再决定是否全量；用 --match-title/--reject-title 按标题过滤。做教学归档时，配合 --write-info-json 把标题、时间、简介一并存下，方便后续检索。站点改版导致下载失败时，第一时间升级到最新版，这是社区响应最快的环节。

总体而言，yt-dlp 是命令行视频下载领域事实上的标准：它把"选流、合并、抽音频、下字幕、批量归档"都收进一个工具，靠高频更新应对站点改版。对自媒体、教学归档和服务器端批处理，它提供了浏览器插件给不了的颗粒度和自动化能力；配合 ffmpeg 与配置文件，日常使用往往就是一条命令。

• GitHub 仓库：yt-dlp/yt-dlp
• 最新发布：Releases
• PyPI 包：yt-dlp
• 支持站点列表：supportedsites.md
• 安装详细文档：Installation Wiki
• ffmpeg 构建：yt-dlp/FFmpeg-Builds
• 问题反馈：GitHub Issues

小结：yt-dlp 用一条命令覆盖选流、合并、抽音频、字幕和批量归档，靠高频更新对抗站点改版。把常用参数写进配置文件，日常就是给一个链接；遇到问题先升级版本，多半已被社区修复。

进阶用法：写脚本时用 Python 库 yt_dlp 的 API，自定义进度钩子和后处理；配 --exec 在下载后自动转码或上传。长期归档建议固定版本并记录 info-json，方便复现。合规使用，尊重版权和目标站点条款。

社区与生态：yt-dlp 是 yt-dlp 的活跃分叉，维护节奏快、支持站点数百个，issue 和 PR 响应积极。它有 Windows、macOS、Linux 各平台包，也有 Docker 和 Python 库；大量第三方工具和脚本直接调用它。想深入可以读它的 extractor 结构，了解站点适配是怎么组织的。

落地建议：先用一条命令下载一个你常看的视频验证环境，再逐步加入抽音频、字幕、批量。把常用参数写进配置文件避免每次敲长命令。做批量归档时先小批量试，确认命名和合并效果，再跑全量。升级到最新版是解决大部分下载失败的第一步。

为什么值得用：浏览器插件只能下单个公开视频，yt-dlp 能选流、合并、抽音频、批量、走登录态，且脚本化可接进自动化。它是命令行里下载视频事实标准，长期维护、更新快。

一句话：把视频下载这件事交给一条命令，剩下的精力留给内容本身。

本文基于官方 README 整理，参数与命令以仓库最新版为准；建议升级到最新 release 再使用。

结语：作为长期活跃的下载工具，yt-dlp 值得放进每台做内容归档和自媒体的机器；把它和 ffmpeg、cookies、配置文件搭配好，日常就是一行命令的事。

祝你下载顺利，常用命令记得写进配置文件。