常見問題排查

本文件彙整了 FlowPick 使用過程中可能遇到的各類問題，按症狀分類提供診斷步驟和解決方案。

問題快速索引

如果你已經知道問題類型，可以直接跳轉到對應章節：

診斷工具與技巧

在深入排查之前，掌握以下診斷工具可以大幅提高效率。

瀏覽器開發者工具

按 F12 或 Ctrl+Shift+I 開啟開發者工具，重點關注以下面板：

常見錯誤資訊速查

在 Console 中看到以下錯誤時，可快速定位問題：

產生診斷報告

在遇到複雜問題時，可以在 Console 中執行以下程式碼產生診斷報告，方便提交 Issue：

// FlowPick 診斷報告產生器
const report = {
  userAgent: navigator.userAgent,
  platform: navigator.platform,
  language: navigator.language,
  fsaAvailable: 'showDirectoryPicker' in window,
  fsaSaveAvailable: 'showSaveFilePicker' in window,
  sharedArrayBuffer: typeof SharedArrayBuffer !== 'undefined',
  crossOriginIsolated: self.crossOriginIsolated,
  serviceWorker: 'serviceWorker' in navigator,
  storage: {
    quota: await navigator.storage?.estimate().catch(() => null),
  },
  timestamp: new Date().toISOString(),
}
console.log('FlowPick 診斷報告:', JSON.stringify(report, null, 2))

媒體偵測問題

擴充功能無法偵測到任何媒體

症狀：開啟包含影片/音訊的網頁後，點擊 FlowPick 圖示，彈出視窗顯示「未偵測到媒體資源」。

診斷步驟：

1. 確認頁面已載入媒體
   在開啟 FlowPick 之前，先讓影片或音訊播放幾秒鐘。許多網站採用懶載入策略，只有使用者互動後才開始載入媒體串流。
2. 重新整理頁面後重試
   擴充功能的媒體偵測依賴於網路請求監控。如果擴充功能在頁面載入之後才安裝或啟用，可能錯過初始請求。重新整理頁面可以觸發新的網路請求。
3. 檢查擴充功能是否已啟用
   點擊擴充功能圖示時，確認彈出視窗正常顯示。如果彈出視窗無法開啟，可能是擴充功能未正確安裝或已被停用。
4. 檢查頁面是否使用非標準協定
   部分網站使用 WebSocket、WebRTC 或自訂加密協定傳輸媒體，這些不在 FlowPick 的偵測範圍內。

常見原因與解決方案：

部分媒體未被偵測到

症狀：FlowPick 偵測到了一些資源，但缺少某些預期的影片或音訊。

可能原因：

• 動態載入時機：某些媒體在使用者捲動或點擊後才載入。嘗試與頁面互動後再開啟 FlowPick
• 過濾設定：檢查是否設定了最小檔案大小過濾，導致小檔案被排除。關於過濾設定，請參閱 設定參考 — 過濾設定
• MIME 類型不標準：伺服器回傳的 Content-Type 不在 FlowPick 的識別列表中。FlowPick 目前識別 25+ 種 MIME 類型，但某些 CDN 可能使用非標準類型

圖片偵測不完整

症狀：頁面上的圖片沒有全部出現在偵測結果中。

原因分析：

• CSS background-image 中的圖片需要頁面完全渲染後才能被偵測
• 懶載入圖片（loading="lazy"）需要捲動到視口內才會載入
• 透過 JavaScript 動態建立的 <img> 元素可能在擴充功能掃描之後才插入 DOM
• Canvas 繪製的圖片內容無法透過 DOM 偵測取得

建議：捲動瀏覽整個頁面後再開啟 FlowPick，確保所有懶載入內容已被觸發。

下載問題

下載無法開始

症狀：點擊下載按鈕後沒有反應，或立即顯示錯誤。

診斷步驟：

1. 檢查瀏覽器下載設定
   確認瀏覽器沒有阻止自動下載。在 Chrome 中：設定 → 隱私與安全 → 網站設定 → 自動下載。
2. 檢查磁碟空間
   確保系統磁碟有足夠的可用空間。影片檔案可能很大（數 GB），下載前請確認空間充足。
3. 檢查是否有其他下載擴充功能衝突
   某些下載管理擴充功能可能攔截或修改下載請求。嘗試暫時停用其他下載相關擴充功能。
4. 檢查瀏覽器主控台錯誤
   按 F12 開啟開發者工具，檢視 Console 面板中的錯誤資訊。常見錯誤包括：
   • Failed to fetch：網路請求失敗
   • CORS error：跨域請求被阻止
   • QuotaExceededError：儲存空間不足

下載速度慢

症狀：下載進度緩慢，速度遠低於網路頻寬。

影響因素與最佳化建議：

診斷流程：

下載速度慢
    │
    ├── 並行數 < 4？
    │   └── 是 → 增加並行數到 4-6，觀察速度變化
    │
    ├── 速度波動大？
    │   └── 是 → 可能是 CDN 限速，嘗試降低並行數到 2-3
    │
    ├── 所有下載都慢？
    │   └── 是 → 檢查網路頻寬，關閉其他佔用頻寬的應用
    │
    └── 僅特定網站慢？
        └── 是 → 該網站的 CDN 可能限速，嘗試不同畫質

下載中途失敗

症狀：下載進行到一定比例後報錯停止。

常見錯誤及處理：

HTTP 403 Forbidden

分片 URL 可能包含時效性權杖，過期後伺服器拒絕存取。解決方案：

• 重新整理頁面取得新的串流位址
• 盡快完成下載，避免權杖過期
• 對於 HLS 串流，權杖通常在 M3U8 清單中，重新取得清單即可

HTTP 404 Not Found

分片已被伺服器刪除（常見於直播回放）。解決方案：

• 確認串流是否仍然可用
• 嘗試選擇不同的畫質（不同畫質可能使用不同的分片檔案）

網路連線中斷

自動重試機制會處理臨時網路波動。如果持續失敗：

• 檢查網路連線穩定性
• 降低並行執行緒數，減少同時進行的連線
• 檢查防火牆或代理設定

CORS 錯誤

線上工具版本受瀏覽器同源策略限制。解決方案：

• 使用瀏覽器擴充功能版本（擴充功能有更寬鬆的網路權限）
• 如果使用線上工具，確認串流 URL 的伺服器允許跨域請求

下載的檔案無法播放

症狀：下載完成，但影片/音訊檔案無法在播放器中開啟。

診斷與修復：

1. 嘗試不同的播放器
   某些播放器對特定編碼或容器的支援有限。推薦使用以下播放器測試：
   • VLC Media Player（相容性最好）
   • MPC-HC
   • PotPlayer
2. 檢查檔案大小
   如果檔案大小明顯小於預期（例如只有幾 KB），可能是下載了 M3U8 清單檔案而非實際影片。確認選擇了正確的資源。
3. 嘗試不同的畫質
   某些畫質的分片可能存在編碼問題。嘗試下載較低或較高的畫質版本。
4. 使用 VLC 的修復功能
   VLC 提供內建的 AVI/MP4 修復功能：
   • 開啟 VLC → 媒體 → 轉換/儲存
   • 加入檔案 → 轉換/儲存
   • 選擇輸出格式 → 開始
5. 檢查合併是否完整
   如果下載過程中瀏覽器崩潰或網路中斷，合併可能不完整。重新下載通常可以解決。

大檔案下載失敗

症狀：下載大檔案（>1GB）時瀏覽器卡頓或崩潰。

原因：Blob 模式下，整個檔案需要載入到記憶體中才能觸發下載。對於超大檔案，這可能導致記憶體不足。

解決方案：

• 使用 File System Access API 的儲存目錄功能，檔案直接寫入磁碟，不佔用記憶體
• 如果瀏覽器不支援 FSA API，FlowPick 會自動使用 StreamSaver.js 串流寫入
• 如果兩種串流寫入都不可用，Blob 模式有 1.5GB 的硬限制，超過此大小的檔案會被拒絕

合併問題

合併後的影片音畫不同步

症狀：影片和音訊軌道存在時間偏移。

原因：這通常發生在 DASH 串流中，影片和音訊分片的時間戳不完全對齊。FlowPick 使用 -c copy 模式合併，不做重新編碼，因此無法修正時間戳偏移。

解決方案：

• 嘗試選擇不同的畫質（不同畫質的音影片同步可能不同）
• 使用 FFmpeg 命令列工具手動重新編碼：

ffmpeg -i output.mp4 -c:v libx264 -c:a aac -async 1 fixed.mp4

合併過程卡住

症狀：進度條長時間停留在「合併中」階段。

原因分析：

• FFmpeg WASM 在處理大量分片時需要較長時間
• 多執行緒模式下 SharedArrayBuffer 不可用時，FFmpeg 退回單執行緒，速度顯著降低
• 記憶體不足導致 WASM 執行緩慢

建議：

• 等待合併完成，大檔案的合併可能需要數分鐘
• 選擇 TS 輸出格式可以跳過 FFmpeg 轉碼，直接二進位拼接（秒級完成）
• 關閉其他佔用記憶體的分頁

瀏覽器相容性問題

SharedArrayBuffer 不可用

症狀：主控台顯示 SharedArrayBuffer is not defined 或 FFmpeg 執行在單執行緒模式。

原因：SharedArrayBuffer 需要頁面設定正確的安全標頭。FlowPick 網站已設定：

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

如果你的部署環境沒有這些標頭，FFmpeg 會自動退回單執行緒模式，功能不受影響但速度較慢。

File System Access API 不可用

症狀：沒有「選擇儲存目錄」按鈕，或點擊後無反應。

支援情況：

在不支援的瀏覽器上，FlowPick 自動使用瀏覽器預設下載方式。

StreamSaver.js 不工作

症狀：主控台顯示 StreamSaver 相關錯誤。

可能原因：

• Service Worker 註冊失敗（某些瀏覽器策略禁止）
• mitm.html 頁面無法載入
• 瀏覽器不支援 WritableStream

FlowPick 會自動降級到 Blob 模式，功能不受影響。

擴充功能特定問題

擴充功能圖示不顯示

1. 點擊瀏覽器工具列的拼圖圖示（擴充功能管理）
2. 找到 FlowPick
3. 點擊圖釘圖示將其固定到工具列

擴充功能被自動停用

Chrome 可能會在以下情況停用擴充功能：

• 擴充功能更新後需要新權限
• 瀏覽器偵測到可疑行為
• 開發者模式擴充功能在瀏覽器重啟後被停用

解決方案：在 chrome://extensions 頁面重新啟用 FlowPick。

快速鍵衝突

預設快速鍵 Alt+Shift+F 和 Alt+Shift+D 可能與其他擴充功能或系統快速鍵衝突。

修改方法：

1. 開啟 chrome://extensions/shortcuts
2. 找到 FlowPick
3. 設定新的快速鍵組合

網路問題排查

代理/VPN 環境

如果你在使用代理或 VPN，下載可能受到影響：

企業網路環境

企業網路通常有更嚴格的安全策略，可能導致以下問題：

• 防火牆阻止非標準連接埠：部分串流媒體使用非 80/443 連接埠，可能被企業防火牆阻止
• Service Worker 被停用：某些企業管理策略禁止 Service Worker，導致 StreamSaver.js 不可用
• 擴充功能安裝受限：企業管理的瀏覽器可能禁止安裝非白名單擴充功能

建議：在企業網路環境中，優先使用線上工具版本（如果可存取），或聯絡 IT 部門了解網路策略。

取得幫助

如果以上方案無法解決你的問題：

1. 檢查 GitHub Issues 是否有類似問題
2. 提交新的 Issue，附上以下資訊：
   • 瀏覽器及版本
   • FlowPick 版本
   • 問題描述和重現步驟
   • 瀏覽器主控台的錯誤日誌（F12 → Console）
   • 問題頁面的 URL（如果可公開存取）
   • 診斷報告 的輸出內容

相關文件

• 已知問題 — 目前版本的技術限制和邊界情況
• 常見問題解答 — 高頻問題與簡明解答
• 下載引擎架構 — 下載引擎的完整技術架構
• 影片嗅探 — 媒體偵測的技術原理
• 格式轉換 — FFmpeg WASM 引擎與輸出格式
• 批次下載 — 佇列排程與並行控制
• 瀏覽器相容性 — 各瀏覽器 API 支援與降級策略
• 線上工具 — 線上工具的使用與限制
• 隱私與安全 — 權限說明與隱私保護
• 設定參考 — 並行數、過濾等設定項
• 安裝指南 — 擴充功能安裝與啟用
• 鍵盤快速鍵 — 快速鍵設定與衝突解決
• 圖片下載 — 圖片偵測與下載功能
• 貢獻指南 — 如何報告 Bug 和貢獻程式碼
• 直播回放儲存 — 超大檔案下載場景
• 圖庫批次儲存 — 圖片批次下載場景

專題故障排查

• M3U8 下載失敗
• DASH 影片沒有聲音
• 影片直連下載失敗