Clash 訂閱匯入解析失敗：連結格式、YAML 縮排與請求標頭檢查清單

先區分下載失敗、解析失敗與節點為空

匯入 Clash 訂閱會經過幾個不同環節：用戶端向訂閱網址發出請求、取得回應本文、轉換或解析內容為設定檔，再交由核心載入。介面上的「更新失敗」可能將這些環節合併顯示。請先開啟用戶端的記錄頁面，記下失敗時間與原始錯誤，再判斷要檢查連結還是設定檔。

Windows 用戶端的選單名稱不盡相同。訂閱入口可能標示為「訂閱」或「設定檔」，記錄通常位於「記錄」頁面。找到出錯的訂閱並更新一次，隨即查看同一時間附近的記錄，避免把節點延遲測試失敗誤認為匯入失敗。

步驟一：確認訂閱連結與 HTTP 回應

複製訂閱網址，而不是帳戶頁面網址

1. 返回服務提供者的訂閱頁面，選擇明確標示為 Clash 或 Clash Meta／mihomo 的訂閱入口。
2. 重新複製完整網址，確認開頭為 https:// 或服務明確提供的 http://，結尾沒有換行、中文標點或多餘空格。
3. 檢查查詢參數是否完整。含有 & 的網址若遭截斷，可能只剩下第一個參數；從網頁原始碼複製時，也要留意是否誤帶字面字串 &。
4. 如果最近重設過訂閱權杖，請在用戶端更新網址。舊連結不會因為再次按下更新就恢復有效。

網址沒有 .yaml 副檔名，不代表格式錯誤。反過來說，網址以 .yaml 結尾，也可能回傳登入頁面或錯誤訊息。真正要檢查的是伺服器回傳的狀態碼與本文。

在 Windows 上儲存實際收到的回應內容

以下命令請在 Windows PowerShell 中執行，使用系統內建的 curl.exe，避免與部分 PowerShell 版本的命令別名混淆。先切換至僅供自己使用的暫存資料夾，再執行命令。網址會透過輸入提示讀取，不必將含有權杖的網址直接寫進命令歷程記錄。

$url = Read-Host '貼上訂閱網址'
curl.exe --location --max-time 30 --dump-header response-headers.txt --output subscription-response.txt -- "$url"
Get-Content .\response-headers.txt
Get-Content .\subscription-response.txt -TotalCount 12
Remove-Variable url

--location 會跟隨重新導向，--max-time 30 則將整體請求時間限制為 30 秒。若出現多組回應標頭，請查看最後一組的狀態碼。命令成功儲存檔案，只代表收到回應，不表示內容一定是有效訂閱。回應標頭也可能包含敏感的重新導向網址，排查完畢後請清除這些檔案。

• 200：接著檢查本文；登入頁面和服務錯誤也可能回傳 200。
• 301、302：確認最後導向的是訂閱內容，而不是登入或驗證頁面。
• 401、403：檢查權杖與存取政策，也可能是伺服器端防護拒絕了請求。
• 404、410：確認訂閱入口是否已變更，並向服務提供者確認連結狀態。
• 429：停止連續更新，依照伺服器提示稍候，以免進一步觸發速率限制。

瀏覽器能開啟，不代表用戶端也能下載。瀏覽器可能帶有登入 Cookie、使用不同的代理路徑，或已通過網頁驗證。請勿以瀏覽器顯示正常的帳戶頁面，作為訂閱有效的依據。

步驟二：辨別回傳內容是 YAML、節點清單還是網頁

查看回應檔案的前幾行，通常就能縮小排查範圍。Content-Type 可供參考，但有些服務會將 YAML 標示為一般文字，因此不能只依據回應標頭下結論。

「節點提供者檔案」和「完整設定檔」也不是同一回事。前者通常只有 proxies 清單，必須由主設定檔中的 proxy-providers 引用。它不一定包含策略群組與規則，因此不要期待將它當成完整設定檔匯入後，就會自動產生所有分流選項。

若必須轉換格式，請優先使用用戶端內建且說明清楚的轉換功能，或服務提供者自家的格式入口。不要將含有權杖的訂閱網址提交給來路不明的線上轉換網站；轉換服務可能讀取網址及回傳內容中的節點憑證。

步驟三：檢查 YAML 縮排、引號與欄位型別

先查看錯誤所在行，再檢查上一層

錯誤訊息中的行號通常是解析器發現問題的位置，不一定是錯誤最初發生的位置。例如上一行少了引號或縮排層級錯誤，可能要到下一行才會報錯。請用本機文字編輯器開啟檔案，顯示行號與空白字元，檢查錯誤行前後各 5 行。

• 層級縮排請使用空格，不要使用 Tab。每層統一縮排 2 個空格會較易閱讀，但最重要的是同一層保持對齊。
• 欄位名稱後使用半形冒號 :，映射值前通常要加空格，例如 mode: rule。
• 清單項目使用半形連字號加空格，例如 - DIRECT；全形破折號不能取代它。
• 字串包含冒號加空格、特殊符號或容易混淆的內容時，請使用成對引號。例如 name: "香港: 01"。
• 同一個映射層級不要重複撰寫 dns、rules 等鍵；不同解析器對重複鍵的處理方式可能不同。

以下是用來理解層級關係的直連測試設定。它沒有遠端節點，無法用來驗證訂閱是否恢復或代理是否連線。僅限在本機測試副本中使用，不要用它覆寫正常訂閱。

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

proxy-groups:
  - name: "本機測試"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,本機測試

proxy-groups 是清單，其中每個策略群組都是一個映射；群組內的 proxies 則是另一個清單。rules 和 proxy-groups 同屬頂層，不能縮排到某個策略群組內。這裡的 7890 只是範例監聽連接埠，實際連接埠請以用戶端顯示為準。

語法解析成功，不代表欄位型別正確

把清單誤寫成字串，仍可能是合法的 YAML，卻不符合核心要求。例如 proxies: "DIRECT" 與上述清單寫法並非相同的資料型別。若看到 cannot unmarshal，也要檢查欄位要求的是字串、數字、布林值、清單還是映射，而不是只調整空格。

若原始訂閱可以載入，但加入覆寫後才出錯，請先停用該訂閱相關的覆寫、合併或指令碼處理，再逐項恢復。用戶端儲存的原始訂閱與最後交給核心的設定可能不同，檢查時應包含最終生效的設定。更多欄位說明請參閱規則語法手冊與DNS 設定參考。

步驟四：比對 User-Agent 與 mihomo 核心支援狀況

同一個連結可能回傳不同格式

部分訂閱介面會依據請求標頭中的 User-Agent 判斷用戶端類型。瀏覽器、命令列工具與用戶端可能取得不同內容，因此前述命令列結果只是一次取樣，不一定與用戶端實際收到的回應完全相同。

如果用戶端提供「訂閱請求標頭」或「User-Agent」設定，請先記下原始值，再核對服務提供者的文件。以下命令會將請求標頭設為 mihomo，僅供比對回應；這不是所有訂閱服務通用的修正值，也不會讓舊版用戶端改用 mihomo 核心。

$url = Read-Host '貼上訂閱網址'
curl.exe --location --max-time 30 --user-agent "mihomo" --output response-mihomo.txt -- "$url"
Get-Content .\response-mihomo.txt -TotalCount 12
Remove-Variable url

如果預設請求回傳節點連結清單，指定請求標頭後卻回傳 YAML，表示伺服器有格式分流機制。請使用服務提供者明確支援的入口或請求標頭，不要連續嘗試大量身分字串。若兩次都回傳驗證網頁，修改 YAML 或更換請求標頭通常無法解決伺服器端的存取限制。

分別記錄介面版本與核心版本

Clash、Clash Premium 與 Clash Meta（現稱 mihomo）支援的功能範圍各有不同。設定中若出現 type: hysteria2、type: vless 等節點類型，請確認目前核心支援相應協定及其參數。只更新用戶端介面，不代表正在執行的核心也已切換。

1. 在用戶端的「關於」或版本資訊頁面記下用戶端版本。
2. 在核心資訊或啟動記錄中記下核心名稱與完整版本號。
3. 比對該版本的設定文件，檢查報錯欄位，尤其是協定類型與傳輸參數。
4. 選擇與核心相符的訂閱格式，或透過用戶端正式提供的更新入口更新核心。

不要刪除 type 或改寫協定名稱來規避錯誤。協定類型決定連線方式，任意修改即使通過結構檢查，通常也無法建立連線。

步驟五：匯入成功但沒有節點，檢查引用關係

節點清單為空時，先確認訂閱原始內容是否包含實際節點，再檢查用戶端的最終設定是否仍保留這些節點。也要區分「節點未下載」與「節點存在，但目前策略群組沒有引用」。

• 直接節點：檢查 proxies 是否為空清單。若回應內容本身就是 proxies: []，請先確認帳戶狀態與訂閱篩選條件。
• 遠端節點提供者：檢查 proxy-providers 的下載記錄。主設定檔下載成功，不代表每個提供者都已更新成功。
• 策略群組引用：使用 use 引用提供者時，名稱必須與 proxy-providers 中的鍵一致。使用 proxies 引用節點時，節點名稱也必須相符。
• 篩選條件：暫時停用自行新增的名稱篩選規則。正規表示式、大小寫或地區名稱變化，都可能讓結果變成零個節點。
• 合併順序：檢查覆寫是否以空清單取代原訂閱中的節點或策略群組。各用戶端的合併機制不同，不要假設清單一定會自動追加。

例如，策略群組設定了 use: [機場節點]，提供者名稱卻是 訂閱節點，兩者不會自動配對。修正引用關係後，再更新對應的提供者並查看記錄。不要只對主訂閱連續按更新。

重新測試順序與問題回報清單

一次只變更一個條件，才能判斷哪項調整有效。先確認訂閱回應正確，再確認 YAML 與核心相容，最後恢復覆寫與網路接管功能。依照以下順序重新測試，通常比同時修改 DNS、連接埠和 TUN 更容易找出問題。

1. 在測試訂閱中匯入原始連結，停用個人覆寫，並更新一次。
2. 確認記錄沒有下載或解析錯誤，並檢查節點數量與策略群組內容。
3. 選擇一個實際節點，再進行延遲測試；測試失敗屬於後續連線排查，不代表訂閱解析失敗。
4. 視需要恢復系統代理並確認瀏覽器可以連線；若需要 TUN，再單獨啟用並測試目標應用程式。
5. 逐一恢復自訂規則、覆寫與篩選設定，每次儲存後都確認核心是否成功載入。

向服務提供者或用戶端專案回報時，請附上 Windows 版本、用戶端版本、核心名稱與版本、失敗時間、HTTP 狀態碼、完整錯誤類型，以及「原始訂閱能否單獨載入」。若問題涉及 YAML，可提供保留層級關係的去識別化片段與原始行號。

不要公開訂閱權杖、伺服器密碼、UUID、完整節點網址或完整回應檔案。若連結已外洩，請先向服務提供者重設權杖，再更新用戶端中的訂閱網址。匯入成功後的檢查步驟，請接著參閱訂閱匯入教學與連線驗證說明。