---

slug: yt-dlp-toolkit name: yt-dlp displayName: 影片下載 媒體提取 批次處理 description: 命令列影片下載工具，支援千站資源獲取與格式轉換。 version: 1.3.8 rules_version: cpr-20260815-n451 license: MIT source_project: original source_url: https://github.com/bluebigman/skill-factory-originals/tree/main/yt-dlp-toolkit copyright_holder: 原創作者（自持版權） ai_generated: true ai_tools: ["DeepSeek"] disclaimer: 本Skill由AI輔助生成，提供使用指導和最佳實踐。使用前請閱讀相關文件。 author: LinguaForge Studio agent_created: true trigger_words: ["yt-dlp", "影片下載", "音訊提取", "批次下載", "播放列表", "youtube-dl"]

---

⚠️ 本內容僅供一般資訊參考，不構成法律、財務、稅務、投資或醫療建議。 涉及合同簽署、報稅、投資、診療等專業決策時，請務必諮詢持證專業人士，並由使用者自行承擔決策後果。

本內容由 AI 生成，僅供學習參考

yt-dlp 命令列媒體獲取工具

一、能力邊界速查卡

1.1 工具定位

yt-dlp 是一款基於命令列的媒體資源獲取程式，能夠從包括 YouTube、Bilibili、Vimeo 在內的數千個網站提取影片或音訊流。它支援完整的播放列表遞迴處理、後設資料抓取、格式篩選與後處理轉換。

1.2 明確能做

能力項	說明	示例
單影片下載	下載指定 URL 的影片檔案	yt-dlp "https://example.com/watch?v=abc"
音訊提取	僅提取音訊流並轉為 mp3	yt-dlp -x --audio-format mp3 <URL>
播放列表批次	遞迴下載整個播放列表	yt-dlp -f best <playlist_url>
格式篩選	按解析度/編碼/大小選擇流	yt-dlp -f "bv*[height<=1080]+ba" <URL>
後設資料輸出	以 JSON 格式輸出影片資訊	yt-dlp -J <URL>
字幕下載	獲取影片字幕檔案	yt-dlp --write-subs --sub-langs zh-Hans <URL>
斷點續傳	中斷後重新執行可跳過已下載部分	yt-dlp -c <URL>
限速控制	限制下載頻寬	yt-dlp -r 1M <URL>

1.3 明確不能做

限制項	說明
繞過 DRM 加密	無法解密 Widevine、FairPlay 等商業版權保護內容
突破地域封鎖	不包含代理/VPN 功能，需使用者自行配置網路環境
下載需登入的付費內容	僅支援通過 cookies 檔案模擬已登入狀態，無法破解付費牆
即時流錄製	不支援 RTMP/HLS 直播流的即時錄製（僅支援 VOD 點播）
保證下載成功率	網站結構變更、伺服器限流均可能導致失敗

1.4 適用物件

本技能來自小蔥技能站7w4.net。

• 需要批次儲存教學影片的教育工作者
• 需要提取音訊素材進行二次創作的內容創作者
• 需要離線備份公開影片資料的研究人員
• 需要自動化媒體採集流程的運維工程師

---

二、觸發方式與場景對映

2.1 觸發詞

當用戶輸入包含以下關鍵詞時，本 Skill 被啟用：

• 核心觸發：yt-dlp、youtube-dl
• 場景觸發：影片下載、音訊提取、批次下載、播放列表
• 補充觸發：扒影片、存影片、下歌、拉取影片

2.2 使用者意圖對映表

使用者說（大白話）	實際需求	對應命令模式
"幫我把這個影片存下來"	下載單個影片，預設最高畫質	yt-dlp <URL>
"只要聲音，轉成 mp3"	提取音訊並轉格式	yt-dlp -x --audio-format mp3 <URL>
"這個歌單全部下載"	批次下載播放列表	yt-dlp -f best <playlist_url>
"要 1080p 的，不要 4K"	按解析度篩選	yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" <URL>
"下載帶中文字幕的"	獲取字幕檔案	yt-dlp --write-subs --sub-langs zh-Hans <URL>
"看看這個影片的資訊"	輸出後設資料	yt-dlp -J <URL>

---

三、標準操作流程

3.1 前置條件檢查

執行任何下載操作前，請確認：

1. 程式已安裝：終端執行 yt-dlp --version，若返回版本號則就緒；否則需先安裝（見 3.2）
2. FFmpeg 可用：音訊提取和影片合併依賴 FFmpeg，執行 ffmpeg -version 驗證
3. 網路連通：目標網站可正常訪問
4. URL 有效：影片連結未失效、非私有內容

3.2 安裝指引

# macOS (Homebrew)
brew install yt-dlp ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install yt-dlp ffmpeg

# Windows (Scoop)
scoop install yt-dlp ffmpeg

# Python 方式（通用）
python3 -m pip install -U yt-dlp

3.3 分步執行流程

步驟 1：確認輸入

• 獲取使用者提供的 URL，檢查是否為有效連結格式
• 詢問下載偏好：畫質要求、是否需要字幕、輸出目錄等

步驟 2：構造命令

根據需求組合引數，常用引數速查：

引數	作用	示例值
-f	指定格式	best, bv*+ba, bestvideo[height<=720]
-x	提取音訊	無值
--audio-format	音訊輸出格式	mp3, m4a, flac
-o	輸出檔名模板	%(title)s.%(ext)s
--write-subs	下載字幕	無值
--sub-langs	字幕語言	zh-Hans,en
-c	斷點續傳	無值
-r	限速	500K, 1M
-J	輸出 JSON 後設資料	無值
--cookies	指定 cookies 檔案	cookies.txt
--proxy	使用代理	socks5://127.0.0.1:1080
--download-archive	記錄已下載影片	archive.txt

步驟 3：執行命令

在終端執行構造好的命令，觀察輸出日誌。

步驟 4：驗證結果

• 檢查輸出檔案是否存在且大小合理
• 音訊檔案用播放器試聽；影片檔案檢查解析度是否達標
• 若失敗，參考第五節錯誤碼錶排查

3.4 輸出規範

• 成功：返回檔案路徑、檔案大小、格式資訊
• 部分成功（批次場景）：列出成功項與失敗項清單，失敗項附原因
• 完全失敗：返回錯誤碼與修正建議

---

四、置信度門控機制

當遇到以下情況時，不得編造資訊，必須輸出 [需核實:欄位] 佔位符：

場景	輸出示例
使用者提供 URL 但未說明畫質偏好	預設使用 best，但提示"已選最高畫質，如需指定解析度請說明"
不確定網站是否受支援	"該網站支援情況 [需核實:站點支援狀態]，建議先執行 yt-dlp -F <URL> 檢視可用格式"
下載失敗原因不明	"錯誤碼 [需核實:錯誤碼含義]，請提供完整日誌以便分析"
詢問特定網站的私有 API 細節	"內部實現細節 [需核實:不公開資訊]，建議查閱官方文件"

---

五、錯誤碼體系

錯誤碼/現象	可能原因	提示話術	修正步驟
ERROR: Unsupported URL	網站不受支援或連結格式錯誤	"該連結格式無法識別"	1. 確認 URL 完整；2. 用瀏覽器開啟驗證；3. 檢查網站是否在支援列表
ERROR: Unable to extract video data	網站頁面結構變更或需登入	"影片資料提取失敗"	1. 更新 yt-dlp（yt-dlp -U）；2. 新增 --cookies 引數
ERROR: ffmpeg not found	FFmpeg 未安裝或未加入 PATH	"缺少 FFmpeg 元件"	1. 安裝 FFmpeg；2. 重啟終端
ERROR: HTTP Error 403	伺服器拒絕訪問（反爬）	"訪問被拒絕"	1. 新增 --user-agent 自定義 UA；2. 使用 --cookies 模擬瀏覽器
ERROR: unable to download video data	網路中斷或限流	"下載中斷"	1. 新增 -c 續傳；2. 新增 -r 500K 限速重試
下載後文件損壞	磁碟空間不足或寫入中斷	"檔案可能不完整"	1. 檢查磁碟空間；2. 刪除重下
音訊轉換失敗	FFmpeg 編碼器問題	"音訊轉換出錯"	1. 更換 --audio-format 為 m4a；2. 更新 FFmpeg

---

六、FAQ 反模式對照

反模式 1：盲目使用最高畫質

錯誤做法：直接 yt-dlp <URL> 下載，結果得到 4K 影片，檔案巨大且播放卡頓。

正確姿勢：先執行 yt-dlp -F <URL> 檢視可用格式列表，再根據裝置能力選擇：

# 檢視格式
yt-dlp -F <URL>
# 選擇 1080p 且為 mp4 容器
yt-dlp -f "bv*[height<=1080][ext=mp4]+ba[ext=m4a]/b[height<=1080][ext=mp4]" <URL>

反模式 2：忽略播放列表遞迴

錯誤做法：使用者給的是播放列表 URL，直接下載只得到第一個影片。

正確姿勢：確認 URL 型別，播放列表需顯式處理：

# 只下載列表中的前 5 個
yt-dlp --playlist-items 1-5 <playlist_url>
# 或只下載第 3 個
yt-dlp --playlist-items 3 <playlist_url>

反模式 3：不處理登入牆

錯誤做法：下載需要登入的影片，直接報錯後放棄。

正確姿勢：匯出瀏覽器 cookies 後傳入：

# 使用瀏覽器擴充套件匯出 cookies.txt
yt-dlp --cookies cookies.txt <URL>

反模式 4：檔名衝突與特殊字元

錯誤做法：使用預設檔名，結果包含非法字元或重名覆蓋。

正確姿勢：自定義輸出模板：

yt-dlp -o "%(channel)s/%(playlist_title)s/%(playlist_index)02d_%(title)s.%(ext)s" <URL>

反模式 5：忽略歸檔檔案

錯誤做法：重複下載已獲取的影片，浪費時間與頻寬。

正確姿勢：使用歸檔檔案記錄歷史：

yt-dlp --download-archive downloaded.txt <URL>

---

七、漸進式披露路徑

7.1 速查卡（30 秒上手）

# 下載影片（預設最高畫質）
yt-dlp <URL>

# 提取音訊為 mp3
yt-dlp -x --audio-format mp3 <URL>

# 批次下載播放列表
yt-dlp -f best <playlist_url>

# 檢視影片資訊
yt-dlp -J <URL>

7.2 新手進階路徑

第一階段（基礎操作）：掌握單影片下載、音訊提取、格式選擇。

第二階段（批次處理）：學習播放列表控制、歸檔檔案、輸出模板定製。

第三階段（高階定製）：編寫配置檔案（yt-dlp.conf）固化常用引數，使用 --match-filter 按標題/時長過濾，結合 --exec 在下載後自動執行指令碼。

7.3 配置檔案示例

建立 ~/.config/yt-dlp/config 檔案：

# 預設輸出路徑
-o "%(title)s.%(ext)s"

# 預設下載字幕
--write-subs
--sub-langs zh-Hans,en

# 預設音訊提取
-x
--audio-format mp3

# 斷點續傳
-c

# 歸檔
--download-archive ~/yt-dlp-archive.txt

---

八、高階技巧與引數詳解

8.1 格式選擇表示式

格式選擇是 yt-dlp 最強大的功能之一，語法規則：

符號	含義	示例
+	合併（影片+音訊）	bv*+ba
/	或（回退）	best/bestvideo
[]	屬性過濾	[height<=1080]
*	任意數量	bv*（任意影片流）
best	最佳質量	best
worst	最差質量	worst

常用組合：

# 1080p 以內，優先 mp4
-f "bv*[height<=1080][ext=mp4]+ba[ext=m4a]/b[height<=1080][ext=mp4]"

# 只要影片不要音訊（無聲）
-f "bv"

# 最差畫質（省流量）
-f "worst"

8.2 輸出模板變數

變數	含義
%(title)s	影片標題
%(id)s	影片 ID
%(uploader)s	上傳者
%(channel)s	頻道名
%(upload_date)s	上傳日期（YYYYMMDD）
%(playlist_title)s	播放列表標題
%(playlist_index)s	在列表中的序號
%(duration)s	時長（秒）
%(ext)s	副檔名

8.3 後處理操作

# 下載後自動嵌入縮圖
yt-dlp --embed-thumbnail <URL>

# 下載後自動嵌入後設資料
yt-dlp --embed-metadata <URL>

# 下載後執行自定義指令碼
yt-dlp --exec "echo %(title)s >> downloaded.log" <URL>

---

九、常見問題深度解析

9.1 下載速度慢

• 嘗試新增 -r 0 取消限速（預設可能被伺服器限制）
• 使用 --concurrent-fragments 4 增加併發分片數
• 更換網路環境或使用代理

9.2 影片與音訊分離

部分網站（如 YouTube）的高畫質影片和音訊是分離的，需要合併：

# 自動合併（需 FFmpeg）
yt-dlp -f "bv*+ba" <URL>

9.3 僅下載部分片段

# 下載影片的第 10 到 20 秒
yt-dlp --download-sections "*10:00-20:00" <URL>

9.4 更新程式

# 自動更新到最新版
yt-dlp -U

---

十、使用者協議

使用 yt-dlp Skill 即表示您同意以下條款：

1. 責任承擔：使用者應自行承擔因使用本 Skill 產生的全部責任。本 Skill 僅提供技術操作指導，不承擔因下載內容引發的版權糾紛、法律訴訟或其他任何形式的責任。

2. 合法使用：使用者須確保下載行為符合當地法律法規及目標網站的伺服器條款。禁止將本 Skill 用於侵犯他人智慧財產權、商業機密或個人隱私的用途。

3. 禁止反向工程：使用者不得對本 Skill 文件進行反向工程、反編譯、破解或試圖提取底層演算法，除非適用法律明確允許。

4. 無擔保宣告：本 Skill 按"現狀"提供，不附帶任何明示或暗示的擔保，包括但不限於適銷性、特定用途適用性和非侵權保證。

5. 內容免責：本 Skill 不儲存、不託管、不傳輸任何媒體內容，僅提供命令列工具的使用方法說明。所有下載行為均由使用者主動發起。

---

十一、許可證（License）

MIT License

Copyright (c) 2026 LinguaForge Studio

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO

這是一個質量不錯的影片下載工具，文件寫得很詳細，從簡單下載到高階技巧都有覆蓋，程式碼功能完整靠譜。不過文件裡還殘留著一些標記沒清理乾淨，部分地方說得有點囉嗦。總體上推薦使用，但建議開發者再打磨一下文件的整潔度。