Clash 訂閱更新失敗、解析錯誤的常見原因與逐步排查

先區分訂閱下載、設定解析與核心載入

「更新失敗」不代表節點失效。訂閱更新通常包含三個步驟：用戶端向訂閱網址發出請求、收到文字後解析設定，再將產生的設定交由核心檢查或載入。任何一步出錯，都可能在介面上顯示紅色提示。排查時應先保留完整錯誤訊息，而不是連續點選更新。

桌面用戶端通常會在「訂閱」或「設定」頁面提供更新入口，並在「日誌」頁面顯示詳細資訊；實際名稱會因用戶端版本而異。請記下用戶端版本、核心名稱與版本、失敗時間，以及這次是手動更新還是排程更新。Clash 與 Clash Meta（現稱 mihomo）的設定支援範圍並不完全相同，只知道應用程式名稱不足以判斷相容性。

訂閱連結失效、授權失敗與伺服器限制

確認複製的是訂閱網址，而非管理頁面

訂閱網址通常包含權杖、查詢參數或專用路徑。帳戶後台網址、登入頁面及 QR Code 圖片網址都不能直接當作訂閱使用。請從服務提供者後台重新複製「Clash」或「mihomo」格式的訂閱入口，並檢查網址開頭或結尾是否多了空格、換行或中文引號。若是從網頁原始碼複製，也要留意 & 可能是 HTML 跳脫後的分隔符號，並非原始網址中的字元。

• 401：通常與授權有關。請確認權杖是否已重設、帳戶是否已過期；實際含義請以服務提供者的說明為準。
• 403：可能是存取政策、來源 IP、User-Agent 或帳戶權限受到限制，不能直接判定為「連結已失效」。
• 404：請確認 API 路徑是否變更、連結是否遭截斷，以及舊訂閱是否已撤銷。
• 429：請停止重複更新，依回應中的 Retry-After 或服務提供者的說明等待；多台裝置排程更新也可能累積觸發限制。
• 502、503、504：請優先考慮伺服器或中間閘道異常，記下發生時間並稍後重試。

瀏覽器能開啟，不代表用戶端收到相同內容

瀏覽器可能帶有登入 Cookie，也可能要通過網頁驗證才會顯示內容；用戶端通常不會共用這些工作階段。即使 HTTP 狀態碼是 200，本文也可能是登入頁、驗證碼頁面或「流量已用完」的文字。請檢查實際回應內容，而不只看狀態碼。切勿將訂閱網址貼到公開的線上檢測工具；權杖通常足以存取帳戶所屬的節點資訊。

本機網路阻擋：依序檢查 DNS、TLS 與代理路徑

下載訂閱所走的網路路徑，不一定與連線節點的路徑相同。有些用戶端會由圖形介面下載設定，另一些則交由獨立元件處理；系統代理、TUN，以及用戶端的「透過代理更新」設定，都可能影響結果。瀏覽器能開啟網站，只能證明瀏覽器目前使用的路徑可用。

1. 檢查系統時間。日期、時區或時鐘明顯錯誤時，TLS 憑證驗證可能會失敗。請先恢復自動校時，再重試一次。
2. 檢查網域解析。Windows 可執行 nslookup，並在後面輸入訂閱主機名稱；macOS、Linux 可使用 dig。此處只輸入主機名稱，不要加上含權杖的路徑。
3. 比較兩種網路。使用相同用戶端與設定，改連手機熱點測試。若熱點可用、目前網路不可用，請優先檢查路由器 DNS、企業網路閘道、入口網站驗證或防火牆。
4. 檢查本機代理監聽狀態。若更新需要使用 127.0.0.1:7890，請確認核心已啟動，且確實在該連接埠監聽。7890 只是常見範例，實際應以目前設定中的 mixed-port 或 HTTP 代理連接埠為準。
5. 一次只切換一個變數。分別測試直連更新，以及透過可用代理更新，並記錄結果。不要同時更換 DNS、啟用 TUN、修改規則，否則無法判斷是哪個變更生效。

connection refused 常見於目標連接埠沒有程序監聽；i/o timeout 則可能發生在連線或讀取階段。請搭配日誌中的目標位址判斷：目標若是本機代理連接埠，先修復本機服務；若是訂閱伺服器，再檢查外部網路連線。

User-Agent 限制與訂閱輸出格式

User-Agent 是 HTTP 請求標頭。訂閱服務可能依此區分用戶端，回傳完整 Clash 設定、只有節點清單，或其他格式。瀏覽器和用戶端向同一網址發出請求，收到不同內容並不罕見。有些服務還要求在連結參數中指定目標格式，單靠修改請求標頭無法解決。

確認請求端，而非只修改 YAML

若用戶端提供「訂閱 User-Agent」選項，請依服務提供者的文件填寫，並記錄原本的值。不要任意偽裝成無關的用戶端；服務提供者可能因此回傳不相容的欄位。首次下載完整設定發生在解析 YAML 之前，因此在該 YAML 中加入請求標頭欄位，通常無法改變這次下載請求。

mihomo 的 proxy-providers 可在支援相應欄位的版本中設定提供者請求參數，但這是核心下載節點提供者資料的請求，與圖形用戶端更新整份訂閱並非同一個入口。若更新失敗，請先確認日誌指的是設定訂閱還是某個 provider。

確認回應內容屬於哪種資料

需要轉換格式時，請優先使用訂閱服務提供者支援的匯出方式，或可信任的本機工具。第三方線上轉換服務能讀取原始連結與節點憑證，應視為具有帳戶存取能力的服務，而非一般文字編輯器。

YAML 解析錯誤：先檢查本文，再查看行號

遇到 mapping values are not allowed、did not find expected key 或 cannot unmarshal 時，請先用本機文字編輯器開啟下載的檔案。若開頭是 <!DOCTYPE html>，應回頭檢查授權與網路；繼續調整 YAML 縮排並無助於解決問題。

逐項檢查縮排、型別與參照

• 縮排：使用空格，不要用 Tab；相同層級的縮排方式須一致。錯誤行號可能只是解析器無法繼續的位置，真正的問題也可能出在前一行。
• 冒號與引號：名稱中若包含「冒號後接空格」，請用引號括起來，例如 name: "香港: 01"。不要用中文彎引號代替 YAML 引號。
• 欄位型別：連接埠通常是數字，布林值通常是 true 或 false；proxies、rules 等清單則須使用正確的連字號結構。
• 重複鍵：不要在同一層級寫兩個 dns: 或 rules: 區塊。不同解析器處理重複鍵的方式可能不同，合併後再進行驗證。
• 名稱參照：策略群組參照的節點、規則指定的策略群組都必須存在，而且名稱須一致。訂閱更新後若節點改名，舊的手動參照也會失效。

以下設定僅用於檢查本機解析與載入流程，所有連線皆為直連，不含遠端節點。請另存為獨立測試檔案，不要覆蓋現有訂閱：

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: "出口選擇"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,出口選擇

這個範例若能通過檢查，但訂閱無法通過，表示問題較可能出在訂閱內容、合併腳本或欄位相容性；這不能證明外部訂閱網址可連線，也不能用來測試代理節點是否連通。若提示連接埠已被使用，請先停止現有執行個體，或改用尚未占用的連接埠再載入。

使用 mihomo 命令列時，可在獨立目錄中執行以下設定檢查。檔名 subscription-test.yaml 指剛才儲存的測試檔案；若設定包含遠端提供者，檢查過程仍可能需要檔案或網路資源，並非純粹的 YAML 語法檢查。

mihomo -t -f subscription-test.yaml

核心不相容、設定合併與更新後載入失敗

YAML 可以解析，不代表核心就能使用。訂閱中的節點協定、傳輸選項與規則類型，可能超出目前核心的支援範圍。遇到 unsupported proxy type 或未知規則類型時，請先記下用戶端「關於」頁面或核心資訊頁顯示的實際版本，再查閱相應核心的文件。應用程式版本與核心版本是兩項不同資訊。

依原始設定、擴充設定與執行設定分層定位

1. 保留下載訂閱取得的原始檔案，確認它能否通過相容核心的檢查。
2. 暫時停用該設定綁定的覆寫、合併或腳本功能；實際入口請以用戶端的設定編輯介面為準。
3. 原始檔案正常時，請逐項恢復本機擴充，檢查是否覆寫了 proxy-groups、rules 或提供者名稱。
4. 若是 provider 失敗，請檢查該 provider 自己的 url、儲存路徑、回應結構與更新日誌，不要只重新整理頂層設定。

不要只為了消除錯誤就刪除所有未知欄位。有些欄位會影響協定交握或傳輸行為，刪除後即使成功載入，節點仍可能無法連線。正確作法是選擇服務提供者明確支援的目標格式，或使用能處理該設定且持續維護的用戶端與核心。

恢復更新後的驗證與問題回報清單

修復完成後，請手動更新一次，檢查更新時間、節點數量與核心載入日誌。節點數量正常只是第一層驗證；還應選擇一個節點，造訪常用網站，確認連線記錄中的策略群組與出口符合預期。延遲測試成功不代表所有流量都能正常使用，規則錯誤仍可能讓特定網域走錯出口。

• 下載成功：日誌沒有 HTTP、DNS 或 TLS 錯誤，收到的是預期格式，而非網頁內容。
• 解析成功：沒有 YAML 行號錯誤、欄位型別錯誤或缺少參照。
• 載入成功：目前執行中的設定確實已切換為更新後的內容，核心沒有回復或繼續使用舊設定。
• 實際連線成功：查看一筆新建立的連線，確認命中的規則與策略群組，避免只根據快取頁面判斷。

提供足夠資訊，同時隱藏存取憑證

向用戶端維護者或訂閱服務提供者回報問題時，請附上作業系統、用戶端版本、核心版本、錯誤時間、HTTP 狀態碼與相關日誌片段，並說明直連與代理更新、目前網路與手機熱點測試的差異。截圖前請遮住完整訂閱網址、權杖、節點密碼及帳戶資料；只遮掉網域、保留查詢參數，仍可能洩漏授權資訊。

排查順序可整理如下：先確認連結與授權，再檢查回應內容和網路路徑，接著處理格式、YAML 與核心相容性，最後檢查本機覆寫。每次只調整一項並記錄前後結果，比反覆重新安裝用戶端更容易找出訂閱更新失敗的具體環節。