88 lines
5.5 KiB
Markdown
88 lines
5.5 KiB
Markdown
---
|
||
name: youtube-download
|
||
description: "Download YouTube videos at the highest available quality (up to 4K) as merged MP4 files with the best audio track (native Opus). Default spec: best video + best audio merged into one MP4 only — do not download a separate audio-only file unless the user explicitly asks for 音频/audio-only. Handles the modern yt-dlp requirements — a JS runtime (bun/deno/node) for YouTube's JS challenges, and browser cookies for videos blocked by bot detection / login / age gates. Use when asked to download, save, or grab a YouTube video, playlist item, or a high-quality/HD/4K copy of a YouTube URL."
|
||
---
|
||
|
||
# YouTube 高清下载 (youtube-download)
|
||
|
||
用 `yt-dlp` 把 YouTube 视频下成本地最高画质 MP4（最高 4K），也可以只下最高音质音频。已经踩平了 2025/2026 年 yt-dlp 下 YouTube 的两个主要坑：需要 JS 运行时、以及机器人检测要 cookie。
|
||
|
||
## 什么时候用
|
||
|
||
用户给一个或多个 YouTube 链接，要求“下载 / 保存 / 下高清 / 下 4K / 下最高画质”时。
|
||
|
||
## 默认规格（每次照此执行）
|
||
|
||
- 默认只下「视频版」：最高画质视频（最高 4K）+ 最佳音质音轨（原生 Opus），合并成单个 MP4，存到用户「下载」文件夹。
|
||
- 除非用户明确说「只要音频 / 音频版 / 单独下音频」，否则**不要**额外下载 audio-only 文件。
|
||
- 链接带 `&list=` / `start_radio=1` 时默认只下当前这一个视频（`--no-playlist`），除非用户要求整个播放列表/电台。
|
||
|
||
## 核心命令（能跑通的那条）
|
||
|
||
```
|
||
yt-dlp \
|
||
--cookies "cookies.txt" \ # 仅当视频需要登录/被机器人拦时必需，见下
|
||
--js-runtimes "bun:$(command -v bun)" \ # 必需：YouTube 现在要求解 JS 挑战（bun/deno/node 任选）
|
||
-f "bestvideo+bestaudio/best" \
|
||
--merge-output-format mp4 \
|
||
--ffmpeg-location "<ffmpeg bin 目录>" \ # 合并视频+音频需要 ffmpeg
|
||
-o "<输出目录>/%(title)s [%(height)sp].%(ext)s" \
|
||
--no-playlist \ # 链接带 &list= 时只下当前这一个
|
||
"https://www.youtube.com/watch?v=VIDEO_ID"
|
||
```
|
||
|
||
**推荐直接用打包好的脚本**（自动准备工具、找 ffmpeg、带 cookie）：
|
||
|
||
- Windows：`scripts/yt-download.ps1`
|
||
- Linux/macOS：`scripts/yt-download.sh`
|
||
|
||
```powershell
|
||
# Windows 示例：下一个或多个视频到「下载」文件夹
|
||
powershell -ExecutionPolicy Bypass -File scripts\yt-download.ps1 "https://www.youtube.com/watch?v=xxxx"
|
||
powershell -ExecutionPolicy Bypass -File scripts\yt-download.ps1 URL1 URL2 URL3
|
||
```
|
||
|
||
```bash
|
||
# Linux/macOS 示例
|
||
bash scripts/yt-download.sh "https://www.youtube.com/watch?v=xxxx"
|
||
```
|
||
|
||
脚本行为：
|
||
- 默认就是最高画质视频 + 最佳音质音轨合并 MP4；不会单独下载音频。
|
||
- JS 运行时自动选 `bun`（已装）；没有则用 `deno`，再退到 `node`。也可用环境变量 `JS_RUNTIME=bun|deno|node` 指定。
|
||
- 找不到 `yt-dlp`（Windows 版还会找 `deno`）会自动下载到脚本旁的 `bin/` 目录。
|
||
- 自动探测 `ffmpeg`（PATH 里没有会提示安装）。
|
||
- 如果脚本目录里存在 `cookies.txt`，会自动带上。
|
||
- 输出文件名格式：`标题 [1080p].mp4`，默认存到当前用户「下载」文件夹（可用 `-OutDir` / `$2` 改）。
|
||
|
||
## 三个关键坑（务必知道）
|
||
|
||
1. **必须有 JS 运行时。** 否则报 `No supported JavaScript runtime could be found` 或直接 `Sign in to confirm you're not a bot`。装 `bun` / `deno` / `node` 任一即可（macOS 上已装 bun，脚本默认用 bun），或给 yt-dlp 传 `--js-runtimes "bun:路径"`。
|
||
- ⚠️ yt-dlp 已把 bun 标记为 deprecated，只支持 bun 1.2.11–1.3.14（本机 1.3.13 可用）。若以后升级 bun 或 yt-dlp 报 bun 不支持，用 `JS_RUNTIME=deno` / `JS_RUNTIME=node` 切换即可（deno 已随 brew 版 yt-dlp 装好）。
|
||
|
||
2. **机器人检测 → 需要 cookie。** 如果 API 返回 `LOGIN_REQUIRED` / “Sign in to confirm you're not a bot” 且 0 个格式，就必须提供你 YouTube 账号的 cookie：
|
||
- 浏览器（登录着 YouTube）装扩展 **“Get cookies.txt LOCALLY”**（开源、纯本地不上传）。
|
||
- **切到 youtube.com 标签页**（当前激活），点扩展图标 → Export，导出 Netscape 格式的 `www.youtube.com_cookies.txt`。
|
||
- 把它改名/放成脚本目录下的 `cookies.txt`（或用 `--cookies` 指定路径）。
|
||
- **公开视频不需要 cookie**，脚本没检测到 cookie 也能下公开视频。
|
||
|
||
3. **cookie 会过期/轮换。** 出现 `The provided YouTube account cookies are no longer valid` 时，按第 2 步重新导出覆盖 `cookies.txt` 即可。公开视频不受影响。
|
||
|
||
## 输出编码说明
|
||
|
||
YouTube 最高画质通常是 **AV1 视频 + Opus 音频**（封装成 mp4）。较新，VLC / PotPlayer / 新版系统播放器都能放；个别老设备放不了。需要更通用时：
|
||
|
||
- 想要 H.264（兼容性最好，但 YouTube 上 H.264 最高只到 1080p）：把格式改成
|
||
`-f "bestvideo[vcodec^=avc1]+bestaudio[ext=m4a]/best[vcodec^=avc1]"`
|
||
- 或下完后用 ffmpeg 转码成 H.264/H.265。
|
||
|
||
## 小抄
|
||
|
||
- 仅当用户明确要求音频时才用：
|
||
- 只下音频（m4a）：`-f "bestaudio[ext=m4a]/bestaudio" -x --audio-format m4a`
|
||
- 只下最高音质音频（保留 YouTube 原生 Opus，不转码、音质最好）：`-f "bestaudio/best" -o "%(title)s.%(ext)s"`
|
||
- 限制最高 1080p：`-f "bestvideo[height<=1080]+bestaudio/best[height<=1080]"`
|
||
- 整个播放列表：去掉 `--no-playlist`
|
||
- 看有哪些格式：`-F`
|
||
- 下字幕：`--write-subs --sub-langs "en,zh-Hans" --convert-subs srt`
|