YouTube 下載器
概述
使用 yt-dlp 和 ffmpeg,從 YouTube 和 HLS 串流平台(Mux、Vimeo 等)啟用可靠的影片與音訊下載。此技能提供以下工作流程:
- 使用 PO Token 提供者或瀏覽器 Cookie 進行 YouTube 下載(最高 4K)
- 使用驗證標頭進行 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 錯誤封鎖,自動設定驗證輔助工具並重試。
可靠下載 SOP(內部)
請遵循此 SOP 以避免常見失敗與混淆:
- 在 Shell 命令中為 URL 加上引號(zsh 會將
?視為 glob 模式)。範例:'https://www.youtube.com/watch?v=VIDEO_ID'。 - 確保 Proxy 同時對 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 能透過相同的 Proxy 連線到 YouTube。
- 如果收到「Only images are available」或「Requested format is not available」,將其視為 PO Token 失敗,並在修復 Token 提供者/瀏覽器狀態後重試。
- 如果收到 SSL EOF 或片段錯誤,將其視為 Proxy/網路問題。使用漸進式格式和/或更好的 Proxy 重試。
代理程式執行檢查清單(內部)
- 執行
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 提供者超時,重新啟動一次並重試。
- 如果設定了系統 Proxy,將其傳遞給提供者容器。如果 Proxy 指向 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)
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/Proxy。
- 不要將 Android 客戶端與 Cookie 一起使用(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:Constant Rate Factor 畫質參數(範圍 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/Proxy。
- 如有必要,使用
web_safari客戶端重試。
僅有圖片可用 / 要求的格式不可用
原因:未套用 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 / 片段錯誤
原因:Proxy 或網路不穩定。
解決方案:
- 使用漸進式格式(非 m3u8)重試。
- 切換到更穩定的 Proxy/節點。
- 避免在下載期間關閉 PO Token 瀏覽器視窗。
下載緩慢或網路錯誤
對於位於中國或嚴格的 Proxy 後方的使用者:
- 下載可能因網路狀況而變慢
- 請給予足夠的時間完成
- 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 可用則使用它,否則切換為基於瀏覽器的提供者)--no-auto-po-token- 停用自動 PO Token 設定--proxy- 用於 yt-dlp 和 PO Token 提供者的 Proxy URL(例如: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 | ✓ | ✓ | ✓ | ✓ | ✓ |