Clash 訂閱失效與解析失敗自查清單：從連結可達性到欄位相容性逐項排查

先區分下載失敗、解析失敗與設定載入失敗

用戶端顯示「更新失敗」時，故障可能發生在三個不同階段。第一階段是透過 HTTPS 請求取得訂閱內容；第二階段是將回應內容識別為 YAML、Base64 節點清單或其他格式；第三階段是把已解析的設定交給 Clash Meta（mihomo）核心載入。三個階段的介面提示經常相似，但檢查方向完全不同。

故障階段	常見現象	優先檢查項目
連結請求	逾時、403、404、連線被重設	狀態碼、DNS、系統代理伺服器、訂閱有效期限
內容解析	unexpected token、invalid YAML、設定為空	回應本文、縮排、編碼、訂閱格式
核心載入	設定已下載，但切換時失敗	欄位相容性、連接埠占用、規則集與核心版本

先記錄完整錯誤文字、發生時間與目前用戶端版本。接著開啟用戶端記錄，將記錄層級暫時調至「資訊」或「除錯」。以 Clash Verge Rev 2.x 為例，可從「設定」→「記錄」進入；不同用戶端的名稱略有差異，也可能位於「設定」→「診斷」。排查完成後再恢復一般記錄層級，避免長期累積大量記錄。

第一步：確認訂閱連結是否能取得內容

檢查 HTTP 狀態碼與重新導向結果

在瀏覽器的私密視窗中開啟訂閱連結，只能作為初步檢查。瀏覽器可能自動攜帶 Cookie、跟隨重新導向或顯示下載檔案，而用戶端使用的是獨立網路請求。更可靠的方法是查看最終狀態碼與回應標頭。Windows 11 可在 PowerShell 中執行以下命令，macOS 與 Linux 則可使用系統內建或本機安裝的 curl。

curl -L --max-redirs 5 --connect-timeout 10 \
  --max-time 30 -D headers.txt \
  -o subscription.txt \
  "https://example.com/api/subscription?token=REDACTED"

-L 允許跟隨 301、302、307 與 308 重新導向，--max-redirs 5 限制重新導向次數，連線逾時設為 10 秒，整體請求時間限制為 30 秒。命令會將回應標頭儲存至 headers.txt，本文儲存至 subscription.txt。測試時應在本機替換範例位址，不要把真實權杖寫入共用腳本。

200：伺服器已回傳內容，繼續檢查本文是否確實為訂閱設定。
301、302、307、308：存在重新導向。若最終仍是重新導向，可能形成迴圈；若導向至登入頁面，用戶端便無法完成互動式登入。
401、403：權杖失效、權限不足、來源限制或請求政策遭攔截。
404、410：訂閱路徑已撤銷、方案遷移後舊位址停止使用，或 URL 在複製時遭截斷。
429：請求頻率過高。暫停自動重新整理，等待伺服器限制視窗結束後再試。
500、502、503、504：伺服器或其上游暫時異常，應結合服務狀態與稍後重試結果判斷。

檢查 URL 是否在複製過程中變更

訂閱位址常含有 ?、&、=、% 等字元。聊天軟體換行、富文字編輯器轉義或手動刪除結尾字元，都可能使權杖失效。位址前後也不應帶有引號、全形空格或換行。若服務提供方控制台提供「複製訂閱」按鈕，應重新複製完整位址並在用戶端新建設定，而不是繼續編輯舊記錄。

也要檢查系統時間。HTTPS 憑證驗證依賴本機時鐘；日期偏差數天時，記錄可能出現憑證尚未生效或已經過期。Windows 可在「設定」→「時間與語言」→「日期與時間」開啟自動設定時間並立即同步；Android 通常位於「設定」→「系統」→「日期與時間」。

排除系統代理伺服器迴路與目前節點故障

訂閱請求可能使用直連，也可能沿用系統代理伺服器。常見的本機混合連接埠為 7890，部分用戶端預設使用 7897；實際數值應以「設定」→「連接埠設定」中的 Mixed Port 為準。如果用戶端核心已停止，而系統代理伺服器仍指向 127.0.0.1:7890，訂閱請求就會連線至沒有監聽服務的本機連接埠。

關閉用戶端中的「系統代理伺服器」，再嘗試更新訂閱。
若直連無法存取訂閱網域，重新啟動核心，選擇已確認可用的節點後再更新。
若已啟用 TUN 模式，先從「設定」→「網路設定」關閉 TUN，建立一次一般請求作為對照。
檢查記錄是否出現 connection refused 127.0.0.1、i/o timeout 或重複轉送至本機連接埠。

TUN 模式本身不參與 YAML 語法解析，但會改變訂閱請求的路由路徑。只有在關閉 TUN 後更新成功，才需要繼續核對路由排除項目、系統代理伺服器狀態與目前節點的可用性；不應直接修改訂閱本文。

第二步：確認回傳內容確實是可用訂閱

查看本文開頭，而不是只看檔案副檔名

訂閱 URL 結尾沒有 .yaml 很常見，判斷依據應是回應內容。使用文字編輯器開啟剛才儲存的 subscription.txt，查看前 20 行。面向 Clash 或 mihomo 的完整 YAML 設定通常會出現 proxies、proxy-groups、rules、proxy-providers 等頂層欄位。

mixed-port: 7890
mode: rule

proxies:
  - name: "Example Node"
    type: ss
    server: 203.0.113.10
    port: 443

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "Example Node"

rules:
  - MATCH,PROXY

如果本文以 <!doctype html>、<html> 或登入表單開頭，實際取得的是網頁。JSON 錯誤物件如 {"code":403,"message":"expired"} 也不是 Clash 設定。此時應處理授權或伺服器問題，修改 YAML 檔案並無作用。

辨識 Base64 節點清單與分享連結

一長段只包含字母、數字、加號、斜線與等號的文字，可能是以 Base64 編碼的通用訂閱。解碼後常見內容是逐行排列的 ss://、trojan://、vmess:// 或 hysteria2:// 分享連結。部分用戶端能匯入這些連結，但將其作為完整 Clash YAML 載入時，會出現頂層類型錯誤或找不到 proxies。

優先回到訂閱提供方的控制台，選擇標示為 Clash、Clash Meta 或 mihomo 的輸出格式。格式轉換會接觸節點憑證，應使用自己控制的本機工具或可信任的伺服器端介面。轉換完成後仍需檢查策略組、規則與 DNS 設定，因為節點清單只描述連線參數，並不等於完整的分流設定。

檢查字元編碼與檔案開頭

YAML 檔案建議儲存為 UTF-8。若文字編輯器顯示大量亂碼，或記錄出現控制字元相關錯誤，應重新以 UTF-8 匯出。檔案開頭的 UTF-8 BOM 通常可由現代解析器處理，但某些舊版用戶端或外層轉換腳本可能將其視為欄位的一部分。排查時可將檔案另存為「UTF-8」，並保留原始副本作為對照。

第三步：逐行定位 YAML 語法與結構錯誤

先查看記錄提供的行號與欄號

典型錯誤包括 did not find expected key、mapping values are not allowed、cannot unmarshal 與 duplicate key。記錄中的行號通常指向解析器最終失去結構的位置，真正的錯誤可能位於前面一至三行。應同時檢查報錯行、上一個項目的縮排，以及引號是否成對。

使用空格縮排，避免混用 Tab 與空格。
同一層級保持一致縮排，常見寫法是每層兩個空格。
列表項目前的連字號後要保留空格，例如 - name: node-a。
名稱包含冒號、井字號、大括號或前後空格時，請以引號包覆。
連接埠應寫成整數，例如 port: 443，不要寫成包含額外文字的值。

# 錯誤：proxy-groups 縮排到 proxies 項目內部
proxies:
  - name: node-a
    type: ss
  proxy-groups:
    - name: PROXY

# 正確：兩個欄位都位於頂層
proxies:
  - name: node-a
    type: ss

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - node-a

區分語法正確與欄位類型正確

通過 YAML 語法檢查並不代表核心能接受所有欄位。例如 port: "443" 在 YAML 中是字串，而協定設定通常需要整數；udp: "true" 是字串，規範值應為布林值 true。記錄出現 cannot unmarshal string into Go value 時，應重點核對值的類型。

欄位	常見正確類型	容易寫錯的形式
`port`	整數	`"443 tcp"`
`udp`	布林值	`"true"`
`proxies`	列表	單一逗號分隔字串
`nameserver`	列表	縮排錯誤的映射物件
`interval`	整數秒數	`24h`

核對策略組引用與規則目標

語法解析完成後，核心還會驗證引用關係。規則結尾的策略名稱必須對應到既有的策略組、代理名稱或內建動作。比如規則寫成 DOMAIN-SUFFIX,example.com,Proxy，設定中卻只有名為 PROXY 的組，大小寫差異就會造成目標不存在。策略組中的節點名稱同樣需要與 proxies 或 use 引用一致。

使用 RULE-SET 時，還要確認相應名稱已在 rule-providers 中定義。provider 的 behavior 應與內容相符：網域集合通常使用 domain，IP 網段集合使用 ipcidr，包含完整規則語句的集合使用 classical。遠端規則集下載失敗時，主訂閱可能已成功解析，記錄會單獨顯示 provider 的 URL、狀態碼或逾時資訊。

第四步：核對 Clash Meta 核心版本與欄位相容性

確認用戶端介面版本與核心版本是兩項資料

桌面用戶端、行動用戶端與 mihomo 核心各有獨立版本。介面升級後，核心不一定同步切換；同一份訂閱在兩台裝置上的表現不同，也經常源於核心版本差異。應從「設定」→「關於」或「設定」→「核心」記錄完整版本資訊。排查時至少寫明用戶端名稱、用戶端版本、核心類型與核心版本，例如「Clash Verge Rev 2.x，mihomo 1.19.x」。

較新的協定與傳輸欄位依賴對應核心支援。設定包含 type: hysteria2、type: tuic、VLESS Reality、WireGuard 或新的 DNS 欄位時，舊版 Clash 核心可能回傳未知類型或未知欄位。解決方向是切換至訂閱目標所需的 mihomo 核心，或讓訂閱服務輸出與現有核心相容的格式，而不是隨意刪除驗證、TLS 或傳輸參數。

以最小設定確認問題屬於節點還是全域設定

保留原始檔案副本後，可以製作一份最小測試設定：只保留一個已知節點、一個策略組與一條 MATCH 規則。若最小設定能夠載入，再逐段加入 DNS、TUN、rule-providers 與進階協定設定，就能定位具體區塊。若單一節點仍報錯，重點檢查該節點的 type、位址、連接埠、驗證欄位與 TLS 參數。

mixed-port: 7890
mode: rule
log-level: info

proxies:
  - name: test-node
    type: socks5
    server: 127.0.0.1
    port: 1080

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - test-node
      - DIRECT

rules:
  - MATCH,PROXY

這份範例僅用於驗證結構是否能被載入，127.0.0.1:1080 必須確實有 SOCKS5 服務才能建立連線。結構測試通過但網路測試失敗，表示 YAML 框架可被核心接受，後續應轉向檢查節點可達性與驗證參數。

檢查連接埠占用與殘留核心程序

設定解析成功後，如果記錄顯示 address already in use，故障點是監聽連接埠而非訂閱格式。常見衝突包括舊核心仍占用 7890、控制器連接埠 9090 被其他執行個體占用，或多個用戶端同時開啟系統代理伺服器。完全退出其他代理伺服器用戶端與殘留核心，再重新載入設定；也可暫時將 Mixed Port 改為 7897 作為對照。

Windows 可執行 netstat -ano | findstr :7890 查看占用程序編號，macOS 與 Linux 可執行 lsof -iTCP:7890 -sTCP:LISTEN。確認程序身分後再結束程序，不要只憑連接埠號處理系統服務。

第五步：依結果採取處理方法

連結失效或授權失敗

從服務控制台重新產生訂閱位址，確認方案狀態與裝置限制。
在用戶端刪除失敗記錄並新建訂閱，避免繼續使用快取 URL。
將自動更新間隔設為合理值，例如 1440 分鐘；短時間內連續重新整理可能觸發 429。
若新連結仍回傳 401 或 403，保留狀態碼、時間與已遮蔽權杖的記錄，聯絡服務提供方。

回傳網頁、JSON 錯誤或通用節點清單

確認複製的是訂閱介面，而不是使用者中心頁面的位址。
選擇 Clash Meta 或 mihomo 格式，重新下載設定。
若只能取得分享連結清單，使用本機轉換流程產生 YAML，並自行補充策略組與規則。
轉換後先以新設定匯入，不要覆蓋仍可正常運作的舊設定。

YAML 欄位或核心不相容

根據記錄行號檢查縮排、引號與欄位類型。
對照目前 mihomo 版本支援的設定結構，確認協定類型與 DNS 欄位。
使用最小設定逐段恢復，定位到單一節點、規則集或 DNS 區塊。
更新核心後重新啟動用戶端，建立新連線再測試，不要沿用舊連線的結果。

完成修復後的驗證記錄

一次完整驗證應涵蓋四項結果：訂閱請求回傳 200；本文是預期格式；設定已由 mihomo 核心載入；實際連線依規則進入對應策略組。僅看到節點數量增加，不能證明規則集、DNS 或 TUN 已正常運作。

手動重新整理一次，記錄耗時。例如在同一網路下連續三次分別為 1.2 秒、1.4 秒與 1.3 秒，結果應相對穩定。
開啟記錄，存取一個直連網域與一個代理網域，確認規則命中的目標符合預期。
切換策略組後建立新連線，舊的 TCP 連線可能繼續沿用原本的出口。
重新啟動用戶端，再載入一次設定，排除只存在於記憶體中的暫時狀態。
恢復合適的自動更新間隔，並確認系統代理伺服器與 TUN 狀態符合日常使用方案。

排查順序應固定：先看 HTTP 狀態與回應本文，再查 YAML 語法與引用關係，最後處理核心版本、連接埠與執行狀態。如此可避免在連結已過期時反覆編輯設定，也能避免將連接埠衝突誤判為訂閱解析錯誤。