1. 先分辨下載失敗、解析失敗與啟用失敗

訂閱更新至少會經過三個階段：用戶端向訂閱網址發出請求、讀取並解析回應內容，再將設定檔交由核心載入。「更新失敗」可能發生在任何階段；節點無法連線，則可能是設定檔已成功載入後才出現的另一個問題。先確認失敗階段，再決定要檢查網路、檔案或核心，避免同時修改 DNS、連接埠和規則。

  1. 保留目前可用的設定檔：在「設定檔」頁面確認目前選取的設定檔，並先備份本機設定檔與覆寫檔案。不要為了測試而刪除唯一可用的訂閱。
  2. 手動更新一次即可：記下點選更新的時間，再開啟「日誌」，查看該時間前後出現的第一則錯誤。最後顯示的「更新失敗」通常只是結果。
  3. 記錄執行環境：在「設定」→「關於」或用戶端版本資訊頁，記下用戶端名稱、版本和核心版本。選單位置會因用戶端而異；圖形介面用戶端的版本不等於 mihomo 核心版本。
  4. 確認失敗範圍：是單一訂閱失敗、所有訂閱都失敗，還是只有某個 proxy-providers 更新失敗？不同情況的排查方向也不同。
日誌線索優先檢查暫時不要做
no such host訂閱網域解析、網路 DNS修改 YAML 縮排
timeout、connection refused請求路徑、代理入口、伺服器連線狀況反覆刪除並重新匯入
HTTP 401、403、429授權狀態、存取限制、更新頻率連續點選更新
yaml、unmarshal回應本文、欄位型別、行號直接判定節點失效
unsupported、not found協定支援、策略名稱、引用關係只因檔案能開啟就判定有效

2. 檢查訂閱連結與 HTTP 回應內容

從服務管理後台重新複製專用訂閱網址

登入服務管理後台，在訂閱區選擇 Clash 或 Mihomo 格式，重新複製完整連結。不要複製瀏覽器網址列中的帳戶頁面網址，也不要把 QR Code 圖片網址當成訂閱網址。連結中 ? 後方的查詢參數通常包含授權資訊；少複製一段，就可能收到登入頁面或權限錯誤。

如果剛在管理後台執行「重設訂閱連結」或「重設權杖」，舊網址可能會立即失效。請更新原設定檔的訂閱網址，不要再使用舊網址發出請求。帳戶到期也可能回傳說明頁，請以服務管理後台的資訊和 HTTP 回應為準，不能把每個 403 都解讀成帳戶到期。

  • 401：通常與驗證有關，請確認權杖及伺服器端的要求。
  • 403：可能是權限、來源限制或防護機制拒絕存取，請依回應本文判斷。
  • 404：確認路徑及連結是否已變更；部分服務也會用此狀態隱藏無效網址。
  • 429：表示請求過於頻繁，請停止重複更新，依伺服器提示或 Retry-After 等待。
  • 5xx：優先懷疑伺服器或中間閘道異常。請保留目前的設定檔，稍後再試。

HTTP 200 不代表回傳的是可用設定檔

成功狀態碼只代表伺服器有回應。如果本文以 <!DOCTYPE html> 或 <html> 開頭，通常是一般網頁、登入頁或驗證頁；如果內容只有 ss://、vmess:// 等分享連結，或是一整段 Base64 文字，則不一定是用戶端目前匯入方式所需的完整 YAML 設定檔。

瀏覽器可以下載、用戶端卻失敗時，也要考慮請求方式不同：瀏覽器可能帶有登入 Cookie、使用不同的代理路徑，伺服器也可能依據用戶端的 User-Agent 回傳不同格式。請優先使用服務管理後台提供的對應用戶端入口，不要先任意偽裝請求標頭。

3. 排查 DNS、代理路徑與 TLS 錯誤

訂閱請求可能由圖形介面用戶端發出，也可能由核心發出。設定檔中的 DNS 設定不一定會控制圖形介面用戶端本身的更新請求；開啟系統代理也不代表更新程式一定會使用該代理。請在訂閱設定的選單中查看更新方式；若有「直接更新」和「透過代理更新」，各測試一次進行比較。

先確認可用的連線出口，避免更新依賴失效設定檔

如果更新必須透過代理，而目前的設定檔已無法使用，就會形成循環依賴。先切換回保留的可用設定檔，再嘗試透過代理更新；或者在允許直接連線至訂閱網域的網路上測試直接更新。TUN 模式會改變流量接管路徑；排查時可先記下原本狀態，再暫時關閉 TUN，使用已確認可用的系統代理或明確指定的代理進行單一變因測試。

以下 PowerShell 指令會透過互動輸入網址，分別測試直接連線與本機 HTTP 代理。範例代理入口為 127.0.0.1:7890；只有用戶端設定顯示 HTTP 或混合連接埠確實為 7890 時，才能直接使用。只有 SOCKS 的連接埠不能直接當成 HTTP 代理使用。

$subscription = Read-Host "貼上訂閱網址，僅在本機檢查"
curl.exe --noproxy "*" --location --connect-timeout 10 --max-time 30 --output NUL --write-out "HTTP %{http_code}\n" "$subscription"
curl.exe --proxy http://127.0.0.1:7890 --noproxy "" --location --connect-timeout 10 --max-time 30 --output NUL --write-out "HTTP %{http_code}\n" "$subscription"
Remove-Variable subscription

此處的 10 秒是連線逾時，30 秒是整個請求的時間上限，並非測速結果。指令只會顯示最後的 HTTP 狀態，不會輸出回應本文；000 不是伺服器狀態碼，應搭配 curl 的錯誤訊息判斷。透過互動輸入可避免將真實連結直接寫入指令歷程記錄，但本機程序檢查仍可能看到執行時參數，不建議在共用裝置上操作。

  • 直接連線失敗、代理成功：檢查訂閱更新是否使用了預期的代理路徑。
  • 直接連線成功、代理失敗：確認本機監聽連接埠、目前的連線出口和更新代理設定。
  • 兩種方式都無法解析網域：先檢查系統 DNS 和訂閱網域是否仍有效，不要只在設定檔中任意新增 DNS 伺服器。
  • 出現 x509 或憑證有效期限錯誤：檢查系統日期、時區、憑證鏈和 HTTPS 檢查軟體；企業網路可請管理員確認信任鏈。

4. 依行號修正 YAML 語法與欄位型別

當日誌出現 yaml: line 12 這類解析階段錯誤時，表示已取得部分內容，但還不能確認內容就是設定檔。先確認收到的不是 HTML 錯誤頁，再用本機文字編輯器查看錯誤行，以及前後各 3 至 5 行。解析器指出的行號可能是「無法繼續讀取」的位置；真正缺少的冒號或引號可能在上一行。

優先檢查四種常見格式錯誤

  1. 縮排混用：YAML 縮排請使用空格，不要使用 Tab；同一層級的縮排要一致。清單項目的 - 必須與子欄位對齊。
  2. 中文標點：將欄位名稱後的全形冒號改為半形 :，並確認逗號和引號沒有被輸入法替換。
  3. 值的型別不符：allow-lan 應為布林值，mixed-port 應為連接埠數值；不要將物件、清單和字串互相替換。
  4. 特殊字元未正確加上引號：包含「冒號後接空格」或「空格後接井字號」的字串要特別留意；網址和名稱可用成對引號括起來。

以下是用來說明結構的最小設定檔，只提供本機混合代理入口，並將流量交給 DIRECT。此設定沒有遠端代理節點，不能用來取代訂閱並期待連線路徑維持不變；啟用後進行測試時，流量會直接連線。

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

proxies: []

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

rules:
  - "MATCH,手動選擇"

如果本機檔案可以載入，但訂閱檔案無法載入，請繼續檢查訂閱內容、合併腳本或覆寫設定。手動修改遠端訂閱通常會在下次更新時被覆蓋；請先在副本上驗證修正，再決定要透過用戶端的持續性覆寫功能調整，或請訂閱提供者修正來源檔案。

5. 確認核心相容性與設定檔引用

YAML 語法正確只代表內容可讀，不代表核心能執行。Clash、Clash Meta（現稱 mihomo）及不同版本支援的協定和欄位各有差異。舊版核心遇到不支援的代理類型時，可能會回報 unsupported proxy type；部分未知欄位也可能遭到忽略，因此「沒有解析錯誤」不代表相關功能已生效。

依照具體錯誤檢查引用關係

  • 不支援的代理類型：確認訂閱匯出的目標與實際執行的核心，使用相容的設定檔，或透過用戶端支援的方式更新核心。
  • 策略或代理不存在：檢查 proxy-groups 中引用的節點和群組名稱，以及規則末尾的策略名稱。名稱必須完全一致，並留意大小寫與尾端空格。
  • 規則集不存在：規則中的 RULE-SET 名稱必須在 rule-providers 中有對應定義，不能只複製引用而漏掉定義。
  • 啟動時回報連接埠已被占用：address already in use 屬於載入或監聽問題。請檢查是否同時執行兩個用戶端，不要再修改訂閱權杖。

也要區分完整設定檔與提供者檔案：完整設定檔可以包含 proxies、proxy-groups、rules 等區段；代理提供者檔案通常提供 proxies 清單，由主設定檔中的 proxy-providers 引用。規則提供者則依宣告的格式提供規則內容，YAML 格式通常使用 payload。兩者用途不同，不能只因副檔名都是 .yaml，就匯入同一個入口。

如果錯誤只指向某個提供者，請先檢查該項目的 URL、格式和更新日誌。主訂閱更新成功，不代表所有提供者也都已成功更新。用戶端的覆寫、合併和腳本也可能修改最終設定；在副本上暫時停用相關處理，比較原始設定與最終執行設定，有助找出錯誤是在哪個步驟引入的。

6. 更新成功後，確認是否已切換至新設定檔

「下載完成」和「目前已啟用」是兩回事。回到「設定檔」頁面，確認目前選取的項目、更新時間和節點數量，再到「代理」頁面確認策略群組內容是否有變化。如果下載成功但核心驗證失敗，用戶端可能會繼續使用舊設定檔；請以載入日誌為準，不要只看更新提示。

  1. 確認更新的是目前正在使用的訂閱，而不是清單中名稱相同的另一個項目。
  2. 查看更新後的載入日誌，確認沒有回退、連接埠占用或引用缺漏。
  3. 在「代理」頁面選擇有效的策略群組，視需要測試單一節點；不要把所有節點的速度測試當成訂閱下載測試。
  4. 如果瀏覽器仍無法連線，再檢查系統代理、TUN 和規則比對；這屬於流量接管或出站連線排查，不再是訂閱解析問題。

不要一直重新啟動，或把自動更新間隔調得太短來確認結果。短時間內重複請求可能觸發 429，反而掩蓋原本的故障。確認一次完整的「請求成功 → 驗證成功 → 載入成功」，比反覆點選更新更有助於判斷問題。

7. 回報問題前的基本資訊清單

本機排查後仍無法解決時，請將問題回報給訂閱提供者或用戶端維護者。只說「匯入失敗」通常不足以重現問題；提供以下資訊可協助對方判斷是伺服器回應、用戶端請求還是核心驗證出了問題。

  • 環境：作業系統、用戶端完整版本、實際核心名稱與版本。
  • 時間與操作：發生錯誤的日期和時區，以及當時是首次匯入、手動更新還是自動更新。
  • 錯誤：第一則相關日誌、HTTP 狀態碼、解析行號及已移除敏感資訊的錯誤上下文。
  • 比較結果：直接更新與透過代理更新的結果，以及其他訂閱是否正常。
  • 設定處理：是否啟用了覆寫、合併腳本、代理提供者或規則提供者。