1. 项目说明
yt-dlp 是一个支持大量视频网站的命令行音视频下载工具。它不是 Web 服务，因此不需要配置端口、数据库或后台进程。
本地部署主要包含三个部分：
- 安装 yt-dlp。
- 安装 FFmpeg，用于合并音视频、转换音频和处理字幕。
- 安装 JavaScript 运行时。完整的 YouTube 支持目前推荐使用 Deno。
请只下载自己拥有、获得授权或当地法律允许下载的内容，并遵守目标网站的服务条款。yt-dlp 不用于绕过 DRM。
2. macOS 部署（推荐）
2.1 检查 Homebrew
打开“终端”，运行：
brew --version如果能够显示版本号，直接进入下一步。如果提示找不到命令，请先从 Homebrew 官网 安装 Homebrew，并按照安装器最后显示的提示将 Homebrew 加入 PATH。
2.2 安装 yt-dlp 和 FFmpeg
brew update
brew install yt-dlp ffmpeg当前 Homebrew 的 yt-dlp 配方会一并处理 Deno 和 yt-dlp-ejs。通常不需要再单独安装 JavaScript 组件。
2.3 验证安装
yt-dlp --version
ffmpeg -version
deno --version三个命令都能正常显示版本信息，即表示部署成功。
2.4 创建下载目录
mkdir -p "$HOME/Downloads/yt-dlp"2.5 首次测试
只读取视频信息，不实际下载：
yt-dlp --simulate "视频网址"确认没有报错后下载：
yt-dlp -P "$HOME/Downloads/yt-dlp" "视频网址"请将 视频网址 替换为实际链接，并保留链接两侧的引号。
3. Windows 部署
打开 PowerShell，依次运行：
winget install --source winget --id yt-dlp.yt-dlp
winget install --source winget --id Gyan.FFmpeg
winget install --source winget --id DenoLand.Deno安装完成后关闭并重新打开 PowerShell，然后验证：
yt-dlp --version
ffmpeg -version
deno --version首次下载：
yt-dlp -P "$HOME\Downloads\yt-dlp" "视频网址"4. Linux 部署
4.1 检查 Python
下面使用的官方 yt-dlp Unix 文件需要 CPython 3.10 或更高版本。先检查：
python3 --version如果没有安装或版本低于 3.10，请先通过发行版的软件仓库安装受支持的 Python 版本。
4.2 安装官方 yt-dlp 文件
mkdir -p "$HOME/.local/bin"
curl -L "https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp" \
-o "$HOME/.local/bin/yt-dlp"
chmod a+rx "$HOME/.local/bin/yt-dlp"确保 ~/.local/bin 已加入 PATH。重新打开终端后检查：
yt-dlp --version4.3 安装 FFmpeg
Ubuntu 或 Debian：
sudo apt update
sudo apt install ffmpegArch Linux：
sudo pacman -Syu ffmpegFedora：
sudo dnf install ffmpeg部分 Fedora 版本需要先启用提供完整 FFmpeg 的软件仓库；请以当前 Fedora 官方文档为准。
4.4 安装 JavaScript 运行时
完整的 YouTube 支持需要 JavaScript 运行时。官方推荐 Deno。Linux 可以使用 Deno 官方安装脚本：
curl -fsSL https://deno.land/install.sh | sh安装器会显示 PATH 配置提示。完成后重新打开终端。其他安装方式见 Deno 官方安装文档。
安装后验证：
ffmpeg -version
deno --version
yt-dlp --version5. 常用命令
# 下载默认最佳画质
yt-dlp "视频网址"
# 指定保存目录
yt-dlp -P "$HOME/Downloads/yt-dlp" "视频网址"
# 只下载当前视频，不下载播放列表
yt-dlp --no-playlist "视频网址"
# 优先输出 MP4
yt-dlp -t mp4 "视频网址"
# 最高不超过 1080p
yt-dlp -S "res:1080" "视频网址"
# 查看全部格式
yt-dlp -F "视频网址"
# 提取 MP3
yt-dlp -t mp3 "视频网址"
# 查看字幕
yt-dlp --list-subs "视频网址"
# 下载中文字幕和英文字幕
yt-dlp --write-subs --write-auto-subs \
--sub-langs "zh.*,en.*" --convert-subs srt "视频网址"
# 使用 Chrome 的登录状态
yt-dlp --cookies-from-browser chrome "视频网址"浏览器 Cookie 相当于登录凭据，请勿导出、上传或分享。
6. 更新
Homebrew 安装
brew update
brew upgrade yt-dlp
brew upgrade ffmpegWindows winget 安装
winget upgrade --source winget --id yt-dlp.yt-dlp
winget upgrade --source winget --id Gyan.FFmpeg
winget upgrade --source winget --id DenoLand.Deno官方独立文件安装
yt-dlp -U如果稳定版更新后仍然因网站改版而无法工作，可以按照官方说明考虑切换到 nightly：
yt-dlp --update-to nightly通过 Homebrew、winget 等包管理器安装时，应优先使用对应包管理器更新，不要混用内置更新方式。
7. 可选配置文件
macOS 和 Linux 推荐位置：
~/.config/yt-dlp/configWindows 推荐位置：
%APPDATA%\yt-dlp\config示例配置：
-P ~/Downloads/yt-dlp
-o %(title)s [%(id)s].%(ext)s
--no-playlist
--embed-metadata保存后，后续只需运行：
yt-dlp "视频网址"临时忽略配置文件：
yt-dlp --ignore-config "视频网址"8. 常见问题
command not found: yt-dlp
重新打开终端。如果仍然失败，检查 yt-dlp 所在目录是否已加入 PATH。
which yt-dlpWindows 可使用：
where.exe yt-dlpffmpeg not found
先确认 FFmpeg 能否运行：
ffmpeg -version如果 FFmpeg 已安装但 yt-dlp 找不到，可以显式指定其目录：
yt-dlp --ffmpeg-location "FFmpeg所在目录" "视频网址"视频突然无法解析
先更新 yt-dlp，再生成详细诊断信息：
yt-dlp -v "视频网址"需要登录或出现年龄限制
使用当前浏览器的登录状态：
yt-dlp --cookies-from-browser chrome "视频网址"也可以将 chrome 替换为 safari、firefox、edge 或 brave。