Clash 訂閱更新失敗、解析錯誤排除：從連結到 YAML 的逐步檢查

先分清下載失敗、解析失敗與節點無法使用

先保留目前可用的設定，再查看更新記錄。訂閱更新分為下載回應、解析設定、載入核心三個階段；節點連線測試則是後續步驟。把這些問題混在一起處理，可能會在連結已失效時反覆修改規則，或在 YAML 格式錯誤時一再切換節點。

ClashX 與使用 mihomo 核心的用戶端，選單名稱和錯誤訊息可能不同。請記下用戶端名稱、用戶端版本、核心名稱與核心版本，不要只記錄視窗標題。外層程式更新至新版，不代表實際執行的核心也已切換。

步驟一：確認複製的是有效的訂閱網址

檢查入口、權杖與方案狀態

1. 前往服務商帳戶頁面，開啟「訂閱」或「匯入」入口，選擇明確標示適用於 Clash 或 mihomo 的設定格式。帳戶登入頁、付款頁和節點介紹頁都不是訂閱網址。
2. 重新複製一次網址，確認開頭是 https://，結尾沒有多出空格、換行或中文標點。請勿刪除查詢字串，其中的參數可能決定帳戶身分與輸出格式。
3. 確認方案尚未到期、流量尚未用完，且訂閱權杖沒有重設。權杖重設後，也要在用戶端更新已儲存的舊網址。
4. 如果取得的是 QR Code 或一鍵匯入連結，請確認用戶端是否支援相應的匯入協定。用來開啟應用程式的連結，與直接回傳設定檔的 HTTPS 網址並非同一種入口。

HTTP 401 常見於驗證失敗；403 可能與帳戶權限、存取政策或安全驗證有關；404 則可能表示路徑已變更。狀態碼只能縮小問題範圍，不能只憑 403 就判定方案已到期。應搭配回應本文與服務商帳戶狀態判斷。

瀏覽器能開啟，不代表用戶端能更新

瀏覽器可能帶有登入 Cookie，或使用與下載訂閱不同的網路路徑。如果開啟連結後出現登入表單、驗證碼或「請啟用 JavaScript」，用戶端通常無法將其解析為設定檔。此時應尋找用戶端可直接讀取的訂閱入口，而不是複製網頁原始碼。

步驟二：檢查訂閱下載的網路路徑

先確認錯誤發生在網域解析、TCP 連線還是 TLS 交握。no such host 指向解析階段；connection refused 表示連線遭拒；certificate has expired 或主機名稱不符屬於憑證問題；context deadline exceeded 則需搭配前後記錄確認逾時位置。

• 網域解析失敗：先確認系統能否解析訂閱網域，再檢查用戶端是否使用獨立 DNS。瀏覽器啟用安全 DNS 時，解析結果不一定能代表系統解析正常。
• 直連逾時：如果目前仍有可用節點，且用戶端支援，可選擇透過該節點更新訂閱；保留舊設定，避免先刪除後失去更新途徑。
• 透過代理更新逾時：確認目前的代理節點可用。如果更新必須依賴已失效的節點，就會陷入「要先更新才能連線、要先連線才能更新」的循環。
• TLS 錯誤：檢查系統日期、時間與時區，並確認訂閱網域的憑證有效。不要把略過憑證驗證當成長期解決方案。

系統代理、TUN 模式與訂閱下載不一定使用相同的網路路徑。有些用戶端透過應用程式層下載訂閱，有些則由核心處理提供者更新。開啟 TUN 後問題消失，只能說明路徑有所變更，無法證明 YAML 已正確，也不能因此要求所有使用者開啟 TUN。

使用本機代理進行可重現測試

以下指令適用於 macOS 或 Linux 的 Bash。透過互動方式輸入網址，避免直接寫入指令歷史；執行時仍可能出現在本機處理程序的參數中，請只在可信任的裝置上操作。回應檔案也包含敏感資訊，請勿上傳。先測試直連，再使用已確認可用的本機混合連接埠進行比對。

umask 077
read -r -s -p '輸入訂閱網址：' SUB_URL
printf '\n'
curl --noproxy '*' --location --connect-timeout 10 --max-time 30 \
  --output subscription-direct.yaml \
  --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.yaml \
  --write-out 'HTTP %{http_code}\n' "$SUB_URL"
unset SUB_URL

7890 只是常見的混合連接埠，請替換成用戶端目前實際監聽的連接埠。若用戶端未監聽該連接埠，第二條指令出現連線遭拒，並不代表訂閱伺服器有問題。這裡沒有使用 --fail，因此收到 HTTP 403 時也可能成功儲存本文；必須同時檢查 HTTP 狀態碼與檔案內容。

步驟三：確認伺服器回傳的內容類型

HTTP 200 只代表請求收到成功回應，不表示回應內容一定是 Clash 設定檔。使用本機文字編輯器開啟剛才儲存的檔案，先查看開頭幾行和頂層欄位，不要直接執行其中任何內容。

完整設定檔與節點提供者不可混用

完整設定檔通常包含代理、策略組與規則，也可以透過 proxy-providers 引用外部節點。節點提供者檔案則通常以 proxies: 開頭，只負責提供節點。將只含節點的檔案當成主設定匯入，可能會得到節點，卻沒有預期的策略組；將完整設定檔當成提供者讀取，也可能導致格式錯誤。

使用提供者時，應分別查看主設定載入結果與提供者下載記錄。主設定語法檢查通過，不代表遠端提供者也已成功更新。如果只有某個策略組是空的，優先檢查該組的 use、提供者狀態與篩選運算式，而不是馬上重設所有設定。

步驟四：依錯誤行號檢查 YAML 與引用名稱

YAML 對縮排很敏感。請使用空格，不要使用 Tab；同一層級的縮排要一致，通常每層使用 2 個空格。出現 mapping values are not allowed 或 did not find expected key 時，從錯誤行往上檢查 3～5 行：真正的問題可能是上一行的引號未閉合，或清單項目縮排錯位。

先用最小設定驗證載入流程

以下是一份不含遠端節點的最小設定，用來判斷「用戶端完全無法載入設定」還是「訂閱內容有問題」。它只提供直連選項，不會建立遠端代理連線。請另存為獨立的測試檔案，不要覆寫原本的訂閱。

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

proxies: []

proxy-groups:
  - name: "手動選擇"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,手動選擇

若測試檔案顯示連接埠已被佔用，請先結束其他代理程序，或改用閒置連接埠並同步調整測試指令。連接埠監聽失敗屬於執行問題，不是 YAML 語法錯誤。若測試設定能正常載入，再回到原訂閱檢查差異。

優先檢查四類結構問題

• 欄位冒號後缺少空格：請寫成 mixed-port: 7890，不要寫成 mixed-port:7890，並期待它仍是相同的鍵值結構。
• 名稱未加引號：節點名稱含有 : 或 # 等特殊組合時，請用引號括住整個名稱；字串內部的引號也必須正確處理。
• 引用名稱不一致：策略組中的節點名稱必須與定義完全一致，包括大小寫、空格和符號。重新命名節點後，也要同步修改引用。
• 頂層欄位重複：不要將兩份設定直接拼成兩個 proxies: 或兩個 rules:。不同解析器可能會拒絕重複的鍵，或採取不同處理方式，不能依賴覆寫行為。

不要只根據副檔名判斷格式。即使檔名是 config.yaml，HTML 錯誤頁也不會因此變成設定檔。也不要批次刪除不理解的欄位：刪掉驗證資訊、傳輸層參數或 TLS 設定，可能讓檔案通過語法檢查，卻導致節點無法連線。

步驟五：核對實際使用的核心與協定相容性

Clash 設定屬於一系列相關但不完全相同的設定格式。mihomo 核心支援的部分協定和欄位，舊版 Clash 核心未必支援。例如訂閱包含 type: hysteria2 時，請確認實際執行的核心支援該節點類型，而不是把類型名稱改成另一種協定。

1. 從用戶端的「關於」頁面或啟動記錄確認版本；如果介面沒有顯示核心資訊，請查看記錄中的核心名稱與版本行。
2. 確認下載套件的平台與架構，並確認更新的是目前正在執行的用戶端，而不是安裝在其他目錄的副本。
3. 如果記錄明確指出代理類型未知或欄位不受支援，請改用服務商提供的相容格式，或改用支援相應功能的用戶端與核心。
4. 不要只為了消除錯誤而刪除 reality-opts、tls 等連線參數。設定檔能被接受，不代表節點就能正確完成交握。

使用 mihomo 內建檢查指令

如果本機已安裝命令列版 mihomo，可在終端機檢查儲存的設定。以下指令假設可執行檔位於 PATH，且測試檔案位於目前目錄；請先確認版本，再執行設定測試。

mihomo -v
mihomo -t -f ./subscription-direct.yaml

測試結果只適用於這份檔案與這個核心。圖形介面用戶端可能還會執行覆寫、合併設定或腳本處理，因此即使終端機測試通過，仍應檢查用戶端實際產生的執行設定。涉及外部資源的設定，也可能在測試或後續載入時需要網路連線；測試通過不代表所有節點都能連線。

更新成功但節點清單空白：檢查篩選條件與設定啟用狀態

先確認目前選取的是剛更新的設定。在部分用戶端中，更新訂閱卡片與切換啟用設定是兩個獨立操作。節點清單沒有變化時，請檢查更新時間、啟用設定標記與載入記錄，不要連續點擊更新，以免觸發請求頻率限制。

• 原始內容就沒有節點：本機檔案為 proxies: []，且沒有其他有效的節點來源時，請向服務商確認帳戶狀態與輸出條件。
• 原始內容有節點，介面卻沒有：檢查是否啟用了名稱搜尋、地區篩選、正規表示式篩選或排除條件；先清除篩選，再進行比對。
• 只有提供者群組是空的：確認策略組透過 use 引用了正確的提供者名稱，並查看該提供者上次下載是否成功。
• 匯入後才出現錯誤：暫時停用自訂覆寫或合併規則進行比對，並保留備份；主訂閱與附加設定可能各自正確，卻在合併後發生名稱衝突。

如果節點已列出，只是延遲測試顯示逾時，請改為排查連線。測試目標無法連線、節點出口故障和本機網路遭到封鎖，都可能造成逾時；這些現象不能反推訂閱解析錯誤。此時繼續調整 YAML 縮排通常沒有幫助。

修復後驗證與可供回報的排障資訊

每次只修改一項，然後重新更新並觀察同一處記錄。一次更換 DNS、核心、訂閱網址與規則，會讓你失去判斷依據。修復後請依下列順序驗收，確認問題不只是錯誤提示消失。

1. 手動更新一次訂閱，確認 HTTP 請求成功，且更新時間有所變更。
2. 確認設定解析與核心載入成功，沒有缺少節點、策略組或提供者的錯誤。
3. 選擇一個節點，透過實際代理路徑瀏覽 HTTPS 網頁，再測試所需的應用程式。瀏覽器運作正常，不代表所有應用程式都已透過代理連線。
4. 重新啟動用戶端，確認啟用的設定仍正確；若使用定時更新，再觀察一次排程是否成功。
5. 刪除排查時產生的敏感回應檔案，並清除不再需要的暫存設定。

依序排查：先確認連結有效，再確認網路能取得回應，接著檢查回應格式、YAML 結構與核心相容性。連接埠與規則基礎可參閱使用說明；帳戶連結與自動更新問題，則可搭配訂閱常見問題繼續排查。