Clash 訂閱更新失敗、解析錯誤排查指南

一、先記錄錯誤，確認問題發生在哪個步驟

更新訂閱並非單一步驟。用戶端會先向訂閱網址發出請求，再解析回傳內容，接著檢查設定與核心是否相容，最後載入節點、代理群組及外部資源。介面顯示「更新失敗」，可能是其中任何一個環節出問題。先確認故障階段，比反覆重新安裝用戶端更有效。

前往用戶端的「訂閱」或「設定檔」頁面，找到發生錯誤的設定檔卡片，記下最近更新時間與設定檔名稱。
開啟「日誌」，清除舊紀錄或記下目前時間，再回到設定檔卡片，只按一次「更新」。不同用戶端的按鈕可能標示為「重新整理」或「更新訂閱」。
回到日誌，找出這次操作後最先出現的錯誤。保留錯誤類型、HTTP 狀態碼、行號與欄位名稱，不要只截取最後一行「失敗」。

日誌或介面提示	通常發生階段	優先檢查項目
`no such host`	網域名稱解析	訂閱網域、目前網路的 DNS
`timeout`、`deadline exceeded`	連線或回應逾時	下載路徑、網路、伺服器回應
HTTP 401、403、404、429	伺服器拒絕請求或回傳錯誤	連結權限、有效期限、請求頻率
`yaml: line 12`	內容解析	實際回應內容、第 12 行附近的縮排
`unsupported proxy type`	設定相容性檢查	協定類型與實際執行的核心
更新完成但沒有節點	設定檔載入或節點提供者更新	啟用的設定檔、篩選條件、providers 日誌

二、檢查連結：確認複製的是訂閱網址

1. 從服務商面板重新複製 Clash 格式的連結

登入訂閱服務商的帳戶面板，找到「訂閱」→「複製訂閱網址」，並選擇明確標示為 Clash 或 Mihomo 的輸出格式。帳戶首頁、方案購買頁面或 QR Code 圖片網址，都不能直接當成設定檔 URL。QR Code 也可能是用來喚起用戶端的匯入指令，建議優先使用面板提供的原始 HTTPS 訂閱網址。

確認開頭是完整的 https://，結尾沒有多出空格、換行或通訊軟體附加的標點符號。
保留 ? 後方的查詢參數；權杖通常位於參數或路徑中，刪除後可能會收到 401 或 403 錯誤。
如果連結曾經重設，舊網址可能會立即失效。請編輯既有設定檔的訂閱 URL 後再更新，避免誤按名稱相同的舊設定檔。
確認帳戶是否到期，以及流量使用狀態。服務商可能透過狀態碼或說明文字指出停用原因，請以帳戶面板資訊為準。

2. 判讀狀態碼時也要查看回應內容

401 通常表示需要有效的身分驗證資訊；403 可能是存取政策、權杖權限或防護機制所致；404 可能代表路徑已變更，也可能是伺服器用來隱藏無效資源的方式。遇到 429 時，請先停止連續重新整理，並依伺服器提示等待；若回應包含 Retry-After，請依該值等待。5xx 通常需要服務商檢查伺服器，但也要留意錯誤頁面是否由中間閘道回傳。

HTTP 200 只表示請求收到成功回應，不代表回應內容一定是 Clash 設定檔。如果內容以 <!DOCTYPE html> 開頭，或包含登入頁、驗證碼、方案說明，代表解析器取得的是網頁。這時調整 YAML 縮排沒有幫助，應先處理連結或伺服器回傳內容。

三、檢查網路：分別測試直連、代理與 DNS

瀏覽器能開啟帳戶面板，不代表用戶端也能下載訂閱。面板與訂閱可能使用不同網域；瀏覽器、用戶端介面程序和核心也可能採用不同的網路路徑。先保持其他設定不變，再逐項比對測試。

確認系統時間。在系統的「日期與時間」設定中開啟自動校時。日期若明顯不正確，可能導致 TLS 憑證有效期限檢查失敗。
檢查下載方式。在設定檔卡片選單或訂閱設定中，尋找「透過代理更新」、「更新方式」等選項。如果用戶端提供此功能，請分別測試直連及透過目前可用的代理更新，並記錄結果。
更換網路重新測試。在允許使用的網路環境中，暫時讓電腦連上手機熱點，再更新同一份訂閱。如果只有某個網路無法更新，請優先檢查該網路的 DNS 解析、驗證機制或存取限制。
檢查本機代理連接埠。開啟用戶端「設定」中的連接埠資訊，確認 HTTP 或 mixed 連接埠確實正在監聽，不要直接套用網路上的預設值。

使用本機指令區分回應與連線問題

熟悉命令列時，可在本機比較兩種請求路徑。以下範例會先以互動方式讀取訂閱網址，避免將完整連結直接寫入命令歷史；代理連接埠 7890 僅供示範，請務必改成用戶端顯示的 HTTP 或 mixed 連接埠。指令適用於常見的 Bash、Zsh 環境，回應內容會寫入目前目錄的本機檔案。

printf '請輸入訂閱網址：'
IFS= read -r SUB_URL
curl --noproxy '*' --location --connect-timeout 10 --max-time 30 \
  --output subscription-direct.txt --write-out 'HTTP %{http_code}\n' "$SUB_URL"
curl --noproxy '' --proxy http://127.0.0.1:7890 --location \
  --connect-timeout 10 --max-time 30 \
  --output subscription-proxy.txt --write-out 'HTTP %{http_code}\n' "$SUB_URL"
unset SUB_URL

這裡設定 10 秒連線逾時與 30 秒整體等待上限，目的是建立可比較的診斷條件，並非建議所有用戶端一律採用這些參數。檔案可能含有節點密碼與權杖，檢查後請妥善刪除，不要同步至公開儲存庫。命令列測試也無法完全重現用戶端的 User-Agent、請求標頭和核心路由；若結果不同，請將差異視為線索，而非直接認定其中一端有問題。

如果日誌顯示 no such host，請先確認系統能否解析訂閱網域。訂閱請求尚未進入核心時，修改 YAML 中的 dns: 不一定會生效。TUN 會改變部分網路流量的接管方式，但無法修復過期權杖或格式錯誤；排查期間請勿同時切換 TUN、DNS 與規則模式。

四、檢查格式：分別處理 YAML 錯誤與核心不相容

確認收到的是完整設定檔，還是只有節點清單

Clash 完整設定檔常見的頂層欄位包括 proxies、proxy-groups、rules，也可能透過 proxy-providers 引用外部節點，因此不能只因為沒有內嵌節點，就判定內容為空。另一方面，逐行列出的協定分享連結、通用 Base64 訂閱，以及僅供 provider 使用的節點清單，都不等於可直接啟用的完整設定檔。

先確認用戶端匯入功能支援的格式，再核對訂閱服務商提供的輸出類型。如果用戶端沒有明確說明支援自動轉換，請選擇相符的格式。需要轉換時，優先使用服務商明確支援的方式或可信任的本機處理流程，避免將存取權杖交給不熟悉的線上服務。

依照錯誤行號檢查縮排與資料類型

日誌中的行號是檢查起點，不一定代表錯誤剛好發生在該行。例如第 12 行顯示錯誤，原因可能是第 11 行少了引號。YAML 縮排應使用空格，避免使用 Tab；冒號後要正確分隔，清單項目前則要加上連字號。以下片段僅用來示意階層，不能單獨作為完整訂閱匯入：

proxy-groups:
  - name: "手動選擇"
    type: select
    proxies:
      - "節點 A"
rules:
  - "MATCH,手動選擇"

mapping values are not allowed：檢查冒號、縮排，以及上一行是否遺漏引號。
cannot unmarshal：確認欄位需要的是字串、清單還是映射，不要只調整空格。
若提示代理群組引用不存在：核對節點名稱與群組名稱，確認大小寫、空格和符號完全一致。
只修改遠端訂閱下載後的快取檔案：下次更新可能會覆蓋修改，應回到來源設定或使用用戶端支援的覆寫層處理。

確認實際執行的核心

前往「設定」→「關於」或用戶端的核心資訊頁，記下用戶端版本與核心版本，兩者並非同一個版本號。Clash Meta 現多稱為 mihomo；不同分支與版本支援的協定和欄位不盡相同。遇到 unsupported proxy type 時，應依照錯誤指出的協定檢查相容性，不要直接刪除該欄位強行載入。

更換用戶端或核心前，請先備份設定，再從可信任的發佈管道取得相容版本。如果目前裝置無法使用所需核心，可詢問服務商是否提供相容格式。單純升級介面程式不一定會切換正在執行的核心，更新後仍應回到核心資訊頁確認。

五、更新成功但節點清單空白：檢查啟用狀態與 providers

「訂閱更新完成」可能只代表主設定檔已下載，不表示主設定檔引用的所有資源都已成功取得。尤其使用 proxy-providers 時，節點檔案是另一個請求，可能有獨立的網址、快取與更新週期。

確認目前啟用的設定檔。回到「設定檔」或「訂閱」頁面，確認選取標記位於剛更新的設定檔。更新設定檔 A，不代表已從設定檔 B 切換至 A。
查看所有代理群組。開啟「代理」頁面，展開實際引用節點的群組。有些首頁只顯示目前的策略，並未列出所有節點。
檢查 provider 狀態。如果用戶端提供「代理提供者」頁面，請查看節點數量、更新時間與錯誤訊息。若沒有獨立頁面，請在日誌中搜尋 provider 名稱與下載錯誤。
檢查篩選條件。正規表示式篩選可能會排除所有節點。請先在備份副本或本機覆寫中移除相關篩選條件進行測試，不要直接破壞唯一可用的設定檔。
檢查代理群組引用。provider 名稱必須與代理群組 use 中的名稱一致。provider 已載入節點，但代理群組沒有引用時，介面上仍可能看不到預期的節點。

如果日誌指出規則提供者 rule-providers 更新失敗，請另外檢查規則檔案網址與格式。規則資源錯誤不代表節點訂閱為空，但可能影響設定檔載入或分流行為，請以實際日誌為準。

六、修復後驗證與尋求協助的資訊清單

修復後依照「更新、載入、連線」三個階段進行驗證。先手動更新一次，確認日誌沒有新的訂閱請求錯誤；接著啟用目標設定檔，確認節點或 provider 數量符合預期；最後選擇一個節點，使用平常需要存取的服務測試連線，並在連線頁面確認實際出口與規則比對結果。

更新驗證：記下操作時間，確認設定檔的更新時間已變更；使用 provider 時，也要檢查其更新時間。
載入驗證：確認沒有 YAML、協定類型或代理群組引用錯誤，且目前啟用的是目標設定檔。
連線驗證：確認系統代理或依需求啟用的 TUN 處於預期狀態，避免將未由代理接管的流量誤判為訂閱故障。
持續性驗證：恢復合理的自動更新排程，並確認下次更新後仍保留所需的本機覆寫。

仍無法解決時，請提供以下資訊

向訂閱服務商或用戶端維護者回報時，請附上作業系統、用戶端版本、核心名稱與版本、故障時間和時區、已遮蔽敏感資訊的完整錯誤訊息，以及直連與代理更新的比對結果。說明收到的是 HTTP 錯誤、網頁內容還是 YAML 解析錯誤，能大幅減少來回確認。

需要提交設定片段時，只保留重現問題所需的欄位，並替換伺服器網址、密碼和存取權杖。如果完整訂閱內容已外洩，請在帳戶面板重設訂閱連結，再更新用戶端儲存的網址。後續可參考完整手冊中的訂閱章節整理設定，避免將遠端訂閱、節點提供者和本機覆寫混在同一層處理。