yt-dlp 下載 Bilibili 字幕指南

問題背景

Bilibili 有嚴格的反爬蟲機制，直接使用 yt-dlp 會遇到 HTTP Error 412: Precondition Failed 錯誤。

解決方案

1. 安裝 curl_cffi（瀏覽器模擬）

yt-dlp 需要 curl_cffi 來模擬瀏覽器繞過反爬蟲：

# 注意：yt-dlp 只支持特定版本
pip install 'curl_cffi>=0.5.10,<0.14' --break-system-packages
Code language: PHP (php)

重要： yt-dlp 2025.12.08 版本只支持 curl_cffi 0.5.10, 0.10.x, 0.11.x, 0.12.x, 0.13.x，不支持 0.14.0+。

2. 驗證 impersonate 功能

/usr/bin/python3 -m yt_dlp --list-impersonate-targets
Code language: PHP (php)

應該看到類似輸出：

Client        OS           Source
------------------------------------
Chrome-131    Android-14   curl_cffi
Firefox-133   Macos-14     curl_cffi
Safari-18.0   Ios-18.0     curl_cffi
...
Code language: CSS (css)

3. 獲取 Bilibili Cookies

Bilibili 字幕需要登入才能下載，需要準備 cookies。

方法 A：瀏覽器擴充功能導出（推薦）

Chrome/Edge 安裝 Get cookies.txt LOCALLY
登入 Bilibili
在 Bilibili 頁面點擊擴充功能 → Export
保存為 cookies.txt

方法 B：直接從瀏覽器讀取（本機執行時）

yt-dlp --cookies-from-browser chrome "URL"
Code language: JavaScript (javascript)

4. 下載字幕

列出可用字幕

/usr/bin/python3 -m yt_dlp \
  --impersonate chrome \
  --cookies cookies.txt \
  --list-subs \
  "https://www.bilibili.com/video/BV11zkVBHED3"
Code language: PHP (php)

輸出範例：

[info] Available subtitles for BV11zkVBHED3:
Language Formats
danmaku  xml      # 彈幕
ai-zh    srt      # AI 生成中文字幕
Code language: PHP (php)

下載字幕（不下載影片）

/usr/bin/python3 -m yt_dlp \
  --impersonate chrome \
  --cookies cookies.txt \
  --write-subs \
  --sub-lang ai-zh \
  --skip-download \
  -o "output/%(title)s.%(ext)s" \
  "https://www.bilibili.com/video/BV11zkVBHED3"
Code language: JavaScript (javascript)

下載所有字幕

/usr/bin/python3 -m yt_dlp \
  --impersonate chrome \
  --cookies cookies.txt \
  --write-subs \
  --all-subs \
  --skip-download \
  "URL"
Code language: JavaScript (javascript)

常用參數說明

參數	說明
`--impersonate chrome`	模擬 Chrome 瀏覽器繞過反爬蟲
`--cookies FILE`	使用 cookies 檔案進行身份驗證
`--cookies-from-browser BROWSER`	直接從瀏覽器讀取 cookies
`--list-subs`	列出可用字幕（不下載）
`--write-subs`	下載字幕
`--sub-lang LANG`	指定字幕語言（如 `ai-zh`, `danmaku`）
`--all-subs`	下載所有語言字幕
`--skip-download`	只下載字幕，不下載影片
`-o TEMPLATE`	輸出檔名模板

Bilibili 字幕類型

類型	說明
`ai-zh`	AI 自動生成的中文字幕
`danmaku`	彈幕（XML 格式）
`zh-Hans`	人工上傳的簡體中文字幕
`zh-Hant`	人工上傳的繁體中文字幕

Cookies 有效期

SESSDATA: 約 6 個月
bili_jct: 約 6 個月
DedeUserID: 約 6 個月

會提前失效的情況：手動登出、修改密碼、異地登入被踢。

常見錯誤

HTTP Error 412: Precondition Failed

原因：未使用 impersonate 或 cookies 無效

解決：

# 確保使用 impersonate
/usr/bin/python3 -m yt_dlp --impersonate chrome ...
Code language: PHP (php)

Impersonate target “chrome” is not available

原因：curl_cffi 未安裝或版本不相容

解決：

pip install 'curl_cffi>=0.5.10,<0.14' --break-system-packages
Code language: JavaScript (javascript)

Subtitles are only available when logged in

原因：未提供 cookies 或 cookies 已過期

解決：重新導出 cookies.txt

完整範例

# 1. 確認環境
/usr/bin/python3 -m yt_dlp --version
/usr/bin/python3 -m yt_dlp --list-impersonate-targets

# 2. 列出字幕
/usr/bin/python3 -m yt_dlp \
  --impersonate chrome \
  --cookies /path/to/cookies.txt \
  --list-subs \
  "https://www.bilibili.com/video/BVxxxxxxxxxx"

# 3. 下載字幕
/usr/bin/python3 -m yt_dlp \
  --impersonate chrome \
  --cookies /path/to/cookies.txt \
  --write-subs \
  --sub-lang ai-zh \
  --skip-download \
  -o "%(title)s.%(ext)s" \
  "https://www.bilibili.com/video/BVxxxxxxxxxx"
Code language: PHP (php)

最後更新：2025-01-27