YouTube 下載器
概述
使用 yt-dlp 和 ffmpeg,從 YouTube 和 HLS 串流平台(Mux、Vimeo 等)可靠地下載影片和音訊。此技能提供以下工作流程:
- YouTube 下載(最高 4K),使用 PO Token 提供者或瀏覽器 Cookie
- 使用驗證標頭下載 HLS 串流
- 處理受保護的內容並排除常見下載失敗
非技術使用者體驗(預設)
假設使用者是非技術背景。不要要求他們執行指令。由您自行執行所有步驟,並用平實的語言回報進度。除非使用者詢問,否則避免提及工具。
預設流程:
- 詢問網址(如果未提供)。
- 擷取影片中繼資料(標題/上傳者/時長/縮圖),並確認與使用者意圖相符。
- 如果 yt-dlp 被「確認你不是機器人」攔截,則改用 YouTube oEmbed 來取得標題/上傳者/縮圖(時長可能未知)。
- 提供簡單的選項(影片 vs. 僅音訊、畫質、字幕、儲存位置)。
- 如果使用者未指定,則採用合理的預設值:
- 最佳畫質下載影片
- 合併輸出為 MP4
- 僅下載單一影片(非播放清單)
- 下載完成後,回報最終檔案路徑、檔案大小和解析度(如果是影片)。
以使用者友善的用語提供選項:
- 「下載最佳畫質的影片(預設)」
- 「僅下載音訊(MP3)」
- 「選擇畫質:1080p / 720p / 480p / 360p」
- 「包含字幕(如果有的話)」
- 「儲存到「下載」資料夾(預設)或告訴我其他資料夾」
始終在可用時渲染縮圖:
- 如果中繼資料包含縮圖網址,請使用 Markdown 圖片語法包含它:
。
在執行額外工作前先詢問:
- 確認播放清單下載(可能很大)。
- 如果缺少相依套件,請確認安裝/升級。
- 在提取瀏覽器 Cookie 前先詢問。
- 如果使用 Cookie,永遠不要在面對使用者的回覆中提及 Cookie 數量或原始 Cookie 細節。應說「使用了您的 Chrome 登入工作階段」。
- 如果需要驗證,自動設定本機 PO Token 輔助工具(無需使用者操作)。如果 Docker 缺失或失敗,不要嘗試安裝 Docker——改為切換到基於瀏覽器的 PO Token 提供者。
法律/安全提醒(簡短):
- 僅在使用者擁有下載內容的權利或權限時才繼續。
回應範本(使用平實語言,不包含指令):

標題:…
頻道:…
時長:…
我可以幫您:
1) 下載影片(最佳畫質,MP4)
2) 僅下載音訊(MP3)
3) 選擇特定畫質(1080p/720p/480p/360p)
4) 包含字幕(如果有的話)
我應該儲存到哪裡?(預設:下載資料夾)
如果使用者說「直接下載」:
- 使用預設值繼續,並在下載完成時確認。
- 如果被 403 錯誤阻擋,自動設定驗證輔助工具並重試。
可靠下載標準作業程序(內部)
遵循此標準作業程序以避免常見失敗和混淆:
- 在 shell 指令中為 URL 加上引號(zsh 會將
?視為萬用字元)。範例:'https://www.youtube.com/watch?v=VIDEO_ID'。 - 確保代理同時對 yt-dlp 和 PO Token 提供者有效(HTTP_PROXY/HTTPS_PROXY/ALL_PROXY)。
- 如果出現「登入以確認你不是機器人」,請要求使用者授權並使用瀏覽器 Cookie。未取得 Cookie 前不要繼續。
- 在下載前啟動 PO Token 提供者(如果無法啟動則快速失敗)。
- 可用時使用 Docker bgutil 提供者。
- 如果 Docker 缺失或失敗,切換到基於瀏覽器的 WPC 提供者。
- 如果正在使用 Cookie,優先使用
web_safari播放器用戶端。否則,對於 PO Token 優先使用mweb。 - 在 WPC 鑄造 Token 期間保持瀏覽器視窗開啟。確保 Chrome 能透過相同的代理連線到 YouTube。
- 如果出現「Only images are available」或「Requested format is not available」,將其視為 PO Token 失敗,並在修復 Token 提供者/瀏覽器狀態後重試。
- 如果出現 SSL EOF 或片段錯誤,將其視為代理/網路問題。使用漸進式格式和/或更好的代理重試。
代理執行檢查清單(內部)
- 執行
scripts/download_video.py URL --info(如果獲得授權,加上--cookies-from-browser chrome)以擷取中繼資料和縮圖。 - 如果 yt-dlp 中繼資料失敗,則依賴腳本的 oEmbed 後備方案來取得標題/上傳者/縮圖,並註明時長可能無法取得。
- 如果存在縮圖網址,使用 Markdown 圖片語法在回應中渲染它。
- 詢問使用者選擇影片或僅音訊,以及(可選)畫質預設。
- 使用友善的預設儲存位置(下載資料夾),除非使用者指定了其他資料夾。
- 對於字幕,使用
--subtitles和請求的--sub-lang執行。 - 下載完成後,以平實語言回報檔案名稱、大小和解析度(如果是影片)。
- 如果下載因 403/片段錯誤而失敗,使用非 m3u8 的漸進式格式重試一次。
- 如果出現「登入以確認你不是機器人」,請求 Cookie 存取權限,並使用 Cookie +
web_safari重試。 - 如果出現「Only images are available」,將其視為 PO Token 失敗,並在修復提供者/瀏覽器狀態後重試。
- 在下載前啟動 PO Token 提供者(預設
--auto-po-token)。如果無法啟動則快速失敗。 - 如果基於 Docker 的提供者失敗(在中國很常見),自動回退到基於瀏覽器的 WPC 提供者(它可能短暫開啟瀏覽器視窗)。
- 如果使用 WPC 提供者,在下載開始前保持瀏覽器視窗開啟。如果瀏覽器啟動失敗,請明確指定 Chrome 路徑。
- 如果 PO Token 提供者超時,重新啟動一次並重試。
- 如果已設定系統代理,將其傳入提供者容器。如果代理指向 127.0.0.1/localhost,將其改寫為
host.docker.internal(適用於 Docker)。
何時使用此技能
當使用者執行以下操作時,應呼叫此技能:
- 要求下載 YouTube 影片或播放清單
- 想要從 YouTube 影片中提取音訊
- 遇到 yt-dlp 下載失敗或可用格式有限的情況
- 需要格式選擇或畫質選項的協助
- 回報僅有低畫質(360p)格式可用
- 詢問以下載特定畫質(1080p、4K 等)的 YouTube 內容
- 需要將下載的 WebM 影片轉換為 MP4 格式以獲得更高的相容性
- 要求下載來自 Mux、Vimeo 或其他串流服務的 HLS 串流(m3u8)
- 需要下載需要驗證標頭的受保護串流
先決條件
1. 驗證 yt-dlp 安裝(自行執行)
which yt-dlp
yt-dlp --version
如果未安裝或版本過舊(< 2025.10.22):
brew upgrade yt-dlp # macOS
# 或
pip install --upgrade yt-dlp # 跨平台
重要:過舊的 yt-dlp 版本會導致 nsig 提取失敗和格式缺失。
2. 檢查當前畫質存取權限(自行執行)
下載前,檢查可用格式:
yt-dlp -F "https://youtu.be/VIDEO_ID"
如果僅顯示格式 18(360p):需要設定 PO Token 提供者才能存取高畫質。
高畫質下載工作流程
步驟 1:安裝 PO Token 提供者(一次性設定)
為獲得 1080p/1440p/4K 存取權限,請將 PO Token 提供者外掛安裝到 yt-dlp 的 Python 環境中:
# 找到 yt-dlp 的 Python 路徑(yt-dlp 所使用的直譯器)
head -1 $(which yt-dlp)
# 使用上面那行得到的直譯器來安裝外掛
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
驗證:再次執行 yt-dlp -F "VIDEO_URL"。尋找格式 137(1080p)、271(1440p)或 313(4K)。
有關詳細的設定說明和疑難排解,請參閱 references/po-token-setup.md。
步驟 2:以最佳畫質下載
安裝 PO Token 提供者後:
# 下載最高至 1080p 的最佳畫質
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# 下載可用的最佳畫質(如果有 4K 則下載 4K)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
步驟 3:驗證下載畫質
# 檢查影片解析度
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4
1080p 的預期輸出:
codec_name=vp9
width=1920
height=1080
替代方法:瀏覽器 Cookie 方法
如果 PO Token 提供者設定有問題,請使用瀏覽器 Cookie:
# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
優點:可存取年齡限制和會員專屬內容。 需求:
- 必須在指定的瀏覽器中登入 YouTube。
- 瀏覽器和 yt-dlp 必須使用相同的 IP/代理。
- 請勿將 Cookie 與 Android 用戶端一起使用(Android 用戶端不支援 Cookie)。
常見任務
僅下載音訊(自行執行)
提取音訊為 MP3:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
自訂輸出目錄(自行執行)
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
下載包含字幕(自行執行)
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
下載播放清單(自行執行)
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
將 WebM 轉換為 MP4(自行執行)
YouTube 的高畫質下載通常使用 WebM 格式(VP9 編解碼器)。將其轉換為 MP4 以獲得更高的相容性:
# 檢查 ffmpeg 是否已安裝
which ffmpeg || brew install ffmpeg # macOS
# 使用良好的畫質設定將 WebM 轉換為 MP4
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"
參數說明:
-c:v libx264:使用 H.264 視訊編解碼器(廣泛相容)-preset medium:在編碼速度和檔案大小之間取得平衡-crf 23:固定品質參數(範圍 18-28,數值越小畫質越好)-c:a aac:使用 AAC 音訊編解碼器-b:a 128k:音訊位元率 128 kbps
提示:轉換可保持 1080p 解析度,並在現代硬體上提供約 6 倍的編碼速度。
疑難排解快速參考
僅有 360p 可用(格式 18)
原因:缺少 PO Token 提供者或 yt-dlp 版本過舊。
解決方案:
- 更新 yt-dlp:
brew upgrade yt-dlp - 安裝 PO Token 提供者(請參閱上面的步驟 1)
- 或使用瀏覽器 Cookie 方法
登入以確認你不是機器人
原因:YouTube 需要驗證才能繼續。
解決方案:
- 請求授權並使用瀏覽器 Cookie(
--cookies-from-browser chrome)。 - 確保瀏覽器和 yt-dlp 使用相同的 IP/代理。
- 如有必要,使用
web_safari用戶端重試。
Only Images Available / Requested Format Not Available
原因:未套用 PO Token,或提供者/瀏覽器驗證失敗。
解決方案:
- 確認 PO Token 提供者在下載前正在執行。
- 如果使用 WPC,請保持瀏覽器視窗開啟。
- 如果正在使用 Cookie,優先使用
web_safari用戶端並重試。
nsig 提取失敗
症狀:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
解決方案:
- 將 yt-dlp 更新至最新版本
- 安裝 PO Token 提供者
- 如果仍然失敗且 PO Token 已停用,請使用 Android 用戶端:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
SSL EOF / 片段錯誤
原因:代理或網路不穩定。
解決方案:
- 使用漸進式格式(非 m3u8)重試。
- 切換到更穩定的代理/節點。
- 避免在下載期間關閉 PO Token 瀏覽器視窗。
下載緩慢或網路錯誤
對於中國或受限代理後方使用者的情況:
- 下載可能因網路狀況而變慢
- 請給予足夠時間完成
- yt-dlp 會自動重試短暫的失敗
PO Token 警告(無害)
WARNING: android client https formats require a GVS PO Token
處理方式:如果下載成功,請忽略。這表示 Android 用戶端在沒有 PO Token 的情況下,可存取的格式有限。
內附腳本參考
scripts/download_video.py
使用這個便利的包裝腳本,預設自動啟動 PO Token 提供者以實現高畫質下載。請自行使用此腳本並將結果回報給使用者,無需要求他們執行指令。
基本用法:
scripts/download_video.py "VIDEO_URL"
引數:
url- YouTube 影片網址(必填)-o, --output-dir- 輸出目錄--output-template- 輸出檔案名稱範本(yt-dlp 語法)-f, --format- 格式規範-q, --quality- 畫質預設(best, 1080p, 720p, 480p, 360p, worst)。預設:best(如果是--audio-only則略過)-a, --audio-only- 提取音訊為 MP3--subtitles- 如果可用,下載字幕--sub-lang- 字幕語言(逗號分隔,預設:en)--cookies-from-browser- 從瀏覽器載入 Cookie(例如 chrome, firefox)--cookies-file- 從 cookies.txt 檔案載入 Cookie--player-client- 使用特定的 YouTube 播放器用戶端(例如 web_safari)--auto-po-token- 自動啟動 PO Token 提供者(預設;如果 Docker 可用則使用 Docker,否則切換到基於瀏覽器的提供者)--no-auto-po-token- 停用自動 PO Token 設定--proxy- yt-dlp 和 PO Token 提供者的代理網址(例如 http://127.0.0.1:1082)--wpc-browser-path- WPC 提供者的瀏覽器可執行檔路徑-F, --list-formats- 列出可用格式--merge-format- 合併輸出容器(例如 mp4, mkv)。預設:mp4--playlist- 允許下載播放清單(預設:僅單一影片)--info- 列印標題/上傳者/時長/縮圖然後退出--no-android-client- 停用 Android 用戶端後備
注意:僅在 PO Token 停用時使用 Android 用戶端。保持 PO Token 啟用以獲得高畫質。
畫質預期
| 設定 | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| 自動 PO Token(預設) | ✓ | ✓ | ✓ | ✓ | ✓ |
| 僅 Android 用戶端 | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO Token 提供者(手動) | ✓ | ✓ | ✓ | ✓ | ✓ |
| 瀏覽器 Cookie | ✓ | ✓ | ✓ |