Clash 訂閱更新失敗或解析錯誤：連結格式、User-Agent 與 YAML 自我檢查清單

1. 分層判斷錯誤：先記錄失敗步驟

先保留目前可用的設定，再手動更新一次訂閱，記下更新時間與完整錯誤訊息。訂閱更新會依序經過網域解析、HTTPS 連線、HTTP 回應、內容解析與設定載入。前一層失敗時，修改後續層的規則通常無濟於事。

桌面用戶端請先開啟訂閱或設定清單，確認更新的是哪一筆，再查看應用程式或核心的記錄。介面名稱會因用戶端而異；「設定檔更新成功」不代表「節點提供者更新成功」。兩者可能使用不同網址，也各自有獨立快取。

2. 連結格式：複製原始訂閱網址，而非登入頁面

從服務商後台重新複製

1. 登入服務商後台，選擇明確標示為 Clash 或與目前核心相容的訂閱格式。
2. 使用複製連結功能，不要從聊天軟體被截斷的預覽中拼湊網址。
3. 確認開頭為 https://，末尾沒有多出空格、換行、中文句號或右括號。
4. 保留完整查詢參數。不要任意刪除 ? 後的內容，也不要截掉以 & 分隔的參數。

網頁原始碼中的 & 是 HTML 字元實體，實際 URL 的參數分隔符應為 &。若複製出的網址真的包含字元序列 &，後續參數可能會被錯誤命名。建議使用後台的複製按鈕重新取得網址，比手動取代更可靠。

clash:// 這類網址可能只是用來呼叫應用程式的匯入指令，不是可直接下載的 HTTPS 訂閱網址。瀏覽器網址列中的會員中心、訂單明細或訂閱說明頁，也不能當成設定網址。瀏覽器能開啟某個頁面，只代表該頁面可存取，不代表它回傳的是 YAML。

檢查登入狀態與重新導向

瀏覽器已有登入 Cookie 時，可能可以正常下載；用戶端沒有這份 Cookie，可能收到登入頁面或拒絕回應。合法的訂閱 API 通常會透過連結權杖等機制授權。請勿將瀏覽器 Cookie 貼到來源不明的指令碼中，應依照服務商文件重新產生可供用戶端使用的網址。

遇到 301、302 或 307 時，請確認最後的網址仍屬於預期的服務。若重新導向到登入頁面、驗證頁面或已失效的網域，應先處理 API 存取問題，而不是調整 YAML 縮排。

3. HTTP 回應：儲存狀態碼、回應標頭與原始本文

Linux、macOS 可在本機終端機使用 curl。Windows PowerShell 請明確呼叫 curl.exe，避免在舊版環境中誤用同名別名。以下指令會透過互動輸入取得網址，避免將完整訂閱網址寫入指令歷程記錄；輸入時仍請留意畫面是否會顯示內容。

# Linux / macOS：在個人目錄建立權限受限的疑難排解資料夾
mkdir -m 700 subscription-check
cd subscription-check
umask 077
read -r -s -p '貼上訂閱 HTTPS 網址：' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --dump-header response-headers.txt \
  --output response-body.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

10 秒是連線逾時，30 秒是整個請求的時間上限；這些只是本次診斷參數，不代表效能保證。指令未使用 --fail，因此伺服器回傳錯誤時也會保留本文，方便區分授權提示與設定資料。若指令出現網路錯誤，請先處理該錯誤；顯示 HTTP 000 不代表伺服器傳回了 000 狀態碼。

• 200：接著檢查本文。登入頁面、驗證頁面和錯誤 JSON 也可能回傳 200。
• 401 / 403：檢查權杖、訂閱狀態、存取限制與回應說明。403 本身無法證明問題一定出在 User-Agent。
• 404 / 410：檢查路徑是否已失效、網域是否已遷移，並從後台重新取得網址。
• 429：若有 Retry-After，請依照指示等待。不要反覆點選更新。
• 500 / 502 / 503：記下時間與狀態碼，稍後再試；重新安裝用戶端通常無法修復伺服器端錯誤。

在本機文字編輯器中開啟 response-body.txt。若內容以 <!DOCTYPE html> 或 <html 開頭，通常代表收到的是網頁；若以 JSON 錯誤物件開頭，應先查看錯誤欄位。Content-Type 可供參考，但有些 API 會將 YAML 標示為一般文字，因此不能只根據回應標頭判斷內容是否有效。

4. User-Agent：只進行有根據的請求比對

部分訂閱 API 會根據 User-Agent 選擇輸出格式，另一些則要求明確指定格式參數。瀏覽器收到節點分享連結、用戶端收到 YAML，可能是同一個 API 採用不同輸出策略。請先查看服務商支援的用戶端說明，不要隨意嘗試瀏覽器識別字串。

在上述終端機工作階段中重新輸入訂閱網址後，可使用以下指令進行一次比對。mihomo 只是測試用的識別字串，不保證與特定圖形介面用戶端實際送出的請求標頭相同，也不保證所有 API 都能辨識。

read -r -s -p '貼上訂閱 HTTPS 網址：' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --user-agent 'mihomo' \
  --dump-header response-headers-ua.txt \
  --output response-body-ua.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

比對兩份本文的頂層欄位與狀態碼。若只有指定請求標頭後才取得相容設定，請確認用戶端是否提供「訂閱請求 User-Agent」設定。全域訂閱匯入與 proxy-providers 下載是兩條不同的路徑，修改其中一處不一定會影響另一處。只有在目前核心文件明確支援時，才在對應的提供者設定中指定請求標頭。

5. 內容格式：完整設定、提供者與分享連結不可混用

Clash 設定並非所有「節點文字」的統稱。常見的回傳內容有三種類型，必須匯入至相對應的位置。副檔名是 .yaml，也不代表內部結構符合核心的要求。

完整設定也可以透過 proxy-providers 取得節點，不一定會內嵌 proxies。因此，看到內嵌清單為空，不能直接斷定訂閱沒有節點；接著應檢查提供者是否下載成功，以及策略群組是否透過 use 引用了正確名稱。

若服務商只回傳編碼後的分享連結，解碼後也不一定是 Clash 設定。不要直接將解碼文字改名為 config.yaml。建議優先使用服務商提供的相應格式，避免將訂閱憑證交給不明的轉換 API。

6. YAML 解析：先修正第一個錯誤，再檢查欄位相容性

縮排、引號與欄位型別

YAML 縮排請使用空格，不要使用 Tab。同一層級的縮排應一致，例如每層兩個空格。若出現「第 18 行附近解析失敗」，也要一併檢查第 17 行：缺少引號、冒號或縮排錯誤，常要到下一行才會被解析器發現。

• 冒號：鍵值之間使用半形 :，後面通常加一個空格。
• 清單：項目使用半形 - 加空格，並確保清單所屬欄位的縮排正確。
• 字串：名稱含有「冒號加空格」時，請用引號括起來，避免被解析為映射結構。
• 型別：連接埠等數值欄位應依核心要求填入整數；布林值請使用 true 或 false，不要填寫中文開關文字。
• 重複鍵：不要重複定義兩段頂層 rules 或 proxy-groups。部分解析器會拒絕載入，其他解析器則可能以後面的值覆蓋前面的值。

以下範例只示範策略群組與規則的結構，不包含遠端節點，也不是可取代訂閱的完整設定。診斷時請勿覆寫目前使用的檔案。

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

rules:
  - "DOMAIN-SUFFIX,example.com,手動選擇"
  - "MATCH,手動選擇"

規則末尾的策略名稱必須與已定義的策略群組或內建策略一致。若將群組名稱從「手動選擇」改成其他名稱，也要同步修改規則中的引用。YAML 語法正確，只代表文字可成功解析，不代表代理協定、欄位組合與名稱引用都有效。

使用實際運作的核心進行測試

mihomo 可在本機執行設定測試。請先透過 mihomo -v 記錄版本，再執行以下指令；檔名請換成儲存在目前目錄中的待測設定檔。

mihomo -v
mihomo -t -f ./config.yaml

請盡量使用圖形介面用戶端實際呼叫的核心版本。使用另一個較新的獨立核心測試，只能確認該核心是否接受設定，無法證明應用程式內建的核心也相容。提供者、規則集與地理資料庫等外部相依項目，仍須搭配啟動記錄檢查。

若出現不支援某種代理類型或欄位的提示，請先確認訂閱的輸出目標。Clash、Clash Meta（mihomo）與不同分支的設定功能並不完全相同。不要為了消除錯誤而刪除協定必要欄位；請改用相容的輸出格式，或確認用戶端支援後再更新核心。

7. 沒有節點與網路失敗：分別驗證下載與載入

更新成功，為什麼清單還是空的？

1. 確認目前使用的設定：更新的是設定 A，實際執行的可能仍是設定 B。更新後請確認目前設定名稱與載入記錄。
2. 檢查提供者：主設定下載成功後，節點提供者仍可能因 DNS、授權或網路錯誤而下載失敗。
3. 檢查篩選條件：filter、exclude-filter 或介面搜尋條件可能已排除所有節點。請先在副本中移除篩選條件，再查看結果。
4. 檢查策略群組引用：提供者名稱必須與策略群組中的 use 一致；只有宣告提供者，不代表所有策略群組都會顯示其節點。
5. 區分清單為空與測試逾時：節點已顯示但延遲測試失敗，屬於連線或測試路徑問題，不再是「訂閱沒有解析出節點」。

系統代理、TUN 與本機連接埠

訂閱請求是否經過代理，取決於用戶端本身的更新設定與執行環境。啟用系統代理不代表背景更新程式一定會使用；啟用 TUN 也無法修復失效權杖或錯誤的 YAML。請先確認請求是直接連線或透過現有代理，再一次只調整一項設定。

若錯誤指向 127.0.0.1:7890，請檢查實際監聽連接埠是否為 7890，以及核心是否正在執行。7890 只是常見範例，並非所有用戶端的固定值。核心啟動失敗後，若更新程式仍依賴這個本機代理，就會形成「設定未載入，訂閱也無法下載」的循環。若用戶端支援，可暫時改用直連更新，並保留原設定以便還原。

若出現 x509、憑證過期或憑證尚未生效等錯誤，請先同步系統日期、時間與時區，再確認目前是否連線到需要登入網頁的公共網路。不要將停用憑證驗證當成長期解決方法。DNS 解析失敗時，請先檢查系統解析狀況與訂閱網域；不要同時大幅調整 DNS、TUN、規則與節點協定，否則很難判斷是哪項設定發揮作用。

8. 驗證恢復狀況：連續確認兩次，再恢復自動更新

1. 手動更新一次，確認回應本文確實是預期的設定，不再出現登入頁面或 API 錯誤。
2. 載入設定，確認記錄中沒有解析錯誤、提供者已完成下載，且策略群組中出現預期的節點。
3. 選擇一個節點建立正常連線。請分別記錄節點可用性與訂閱更新結果，不要用單一「成功」狀態取代所有驗證。
4. 間隔一段合理時間後再次更新，確認成功並非暫時依賴舊快取，接著恢復原本的自動更新週期。

若問題仍未解決，請向服務商提供用戶端名稱、實際核心版本、系統平台、錯誤時間、HTTP 狀態碼與已遮蔽敏感資訊的錯誤行。不要傳送完整權杖、節點密碼或整份原始設定。刪除本機疑難排解檔案前，請先保留不含憑證的結論；回應標頭也可能包含 Cookie 或帶有權杖的重新導向網址，應一併視為敏感資料處理。

需要重新選擇用戶端，請先參閱用戶端比較；想了解規則、策略群組與提供者的差異，可查看概念速查。復原順序不變：連結有效、回應正確、格式相容、成功載入，最後才測試連線。