先判斷失敗發生在哪個步驟
用戶端中的「更新訂閱」並不是單一動作，至少包含網域解析、建立連線、傳送 HTTP 請求、接收回應、解析設定、寫入本機檔案，以及重新載入核心等階段。介面只顯示「更新失敗」時，應先從日誌或回應內容確認具體階段。直接重複點選通常不會改變結果，還可能觸發訂閱服務的頻率限制。
常見桌面用戶端會將訂閱放在「設定」、「訂閱」或「Profiles」頁面。以採用 mihomo 核心的用戶端為例，可以先進入「設定」→「訂閱」，對目標設定執行一次手動更新，再到「日誌」頁面查看同一時間產生的紀錄。若用戶端提供日誌層級，排查期間選用 Info；只有錯誤資訊太少時，才暫時切換至 Debug。
| 日誌或現象 | 通常對應的階段 | 優先檢查項目 |
|---|---|---|
no such host、網域解析失敗 |
DNS 解析 | DNS 設定、網路連線、訂閱網域是否仍然有效 |
timeout、連線逾時 |
建立連線或等待回應 | 直連與代理路徑、防火牆、伺服器狀態 |
401 或 403 |
伺服器驗證 | 權杖、連結有效期限、User-Agent 與存取限制 |
404 或 410 |
訂閱網址失效 | 重新取得完整訂閱連結 |
| YAML、Base64 或欄位解析錯誤 | 設定解析 | 回應格式、轉換類型、用戶端相容性 |
| 下載成功但設定沒有變更 | 儲存或重新載入 | 本機快取、目前啟用的設定、檔案寫入權限 |
區分訂閱下載與節點連線能力
訂閱更新成功，只代表用戶端已取得並解析設定，不表示其中的代理節點一定能連線。反過來，現有節點可以使用，也不代表訂閱網址仍然有效。本機設定可能是數天前儲存的快取，節點仍能運作，但原本的訂閱權杖已經過期。
- 更新失敗但舊節點可用：重點檢查訂閱網址、驗證與更新路徑。
- 更新成功但所有節點都逾時：重點檢查節點參數、網路限制與系統時間。
- 節點數量變成 0：先檢查伺服器回傳內容，不要只看 HTTP 狀態碼。
- 下載設定後無法啟用：檢查 YAML 語法、欄位相容性與核心版本。
訂閱連結過期、截斷與驗證失敗
訂閱網址通常包含存取權杖。權杖被重設、方案狀態變更、連結設定了有效期限，或伺服器遷移路徑後，舊網址就可能回傳 401、403、404 或 410。部分服務會回傳狀態碼 200，但正文其實是登入頁面或一段 JSON 錯誤訊息，因此「下載完成」仍可能在解析階段失敗。
確認複製的是完整連結
長連結經過聊天軟體、QR Code 辨識或手動換行後，容易遺失結尾字元。也要留意查詢參數中的 &：從網頁複製時，應取得瀏覽器網址列中的真實連結，而不是將 HTML 中顯示的轉義文字原樣貼入用戶端。連結前後也不應帶有空格、中文引號或換行。
- 回到訂閱服務的管理頁面，重新複製 Clash 或 mihomo 對應的訂閱網址。
- 在用戶端新增一筆暫時訂閱，不要急著刪除舊設定。
- 執行手動更新，比對節點數量、策略群組名稱與更新時間。
- 確認新設定可以載入後，再停用已失效的舊訂閱。
訂閱連結等同於存取憑據，不適合貼到公開日誌、截圖或線上 YAML 檢查網站。需要提供錯誤資訊時，可以保留網域與狀態碼，但應遮蔽路徑中的權杖和查詢參數。
使用命令列查看狀態碼與回應類型
瀏覽器可能會自動跳轉至登入頁面，也可能使用與 Clash 不同的請求標頭。透過命令列測試更容易看到狀態碼與回應標頭。Windows 可在 PowerShell 中呼叫 curl.exe，macOS 與 Linux 則可直接使用 curl。以下使用保留網域示範，不包含真實訂閱憑據。
curl -I -L --max-time 15 "https://sub.example.com/clash/demo-token"
curl -L --max-time 15 -o subscription.yaml "https://sub.example.com/clash/demo-token"-I 只會請求回應標頭，但少數訂閱伺服器不接受 HEAD 請求。如果第一個命令回傳 405，應以第二個實際 GET 請求為準。下載完成後先查看檔案開頭：HTML 通常以 <!doctype html> 或 <html 開始，JSON 錯誤通常以大括號開頭，Clash YAML 則通常能看到 proxies:、proxy-groups:、rules: 等欄位。
User-Agent 驗證與格式不相容
部分訂閱服務會根據 User-Agent 回傳不同格式，或只允許特定用戶端識別。瀏覽器存取正常，但用戶端更新回傳 403，或同一網址在不同用戶端取得不同內容時，就需要檢查 UA。常見識別包括 clash、Clash.Meta 和用戶端自身名稱，但伺服器接受哪一種取決於其設定，不能靠不斷隨機更換來判斷。
先在訂閱服務說明中確認建議使用的 UA。若用戶端提供設定選項，可在「設定」→「參數設定」或訂閱編輯視窗中尋找「User-Agent」、「訂閱請求標頭」等選項。選單名稱會隨用戶端版本變更；沒有該選項時，不應直接修改核心設定來猜測，因為主設定中的代理規則不等同於訂閱管理器的 HTTP 請求標頭。
curl -L --max-time 15 \
-A "Clash.Meta" \
-o subscription.yaml \
"https://sub.example.com/clash/demo-token"如果預設請求回傳 403，而使用服務方明確要求的 UA 後取得 200 和有效 YAML，就可以將問題定位為請求標頭驗證。若兩種請求都回傳相同錯誤，則繼續檢查權杖、來源 IP、請求頻率與服務狀態。
Base64 節點清單與 Clash YAML 並非相同格式
通用訂閱可能是一段 Base64 文字，解碼後包含多行 URI；Clash 設定通常則是結構化 YAML。若用戶端只接受 Clash YAML，匯入通用訂閱就可能出現「缺少 proxies」、「無法解析設定」或節點數量為 0。此時應在伺服器端選擇 Clash、Clash Meta 或 mihomo 輸出類型，而不是手動修改檔案副檔名。
mihomo 對 Clash 設定維持廣泛相容性，但擴充欄位不一定能被舊版 Clash 核心識別。例如某些新協定參數、規則提供器選項與 DNS 欄位，在舊核心中可能出現未知欄位或載入失敗。遇到這種情況，應先查看用戶端的核心版本，再選擇相符的訂閱範本。更新圖形用戶端不一定會自動切換核心，核心版本需要在「設定」→「核心」或「關於」頁面另外確認。
YAML 可以開啟，仍可能無法載入
- 同一層級的縮排必須一致，不能混用 Tab 與空格。
- 策略群組引用的節點或提供器名稱必須存在。
rules中使用的目標策略群組必須已經定義。- 連接埠應為有效整數，不能被引號、中文符號或註解破壞。
- 伺服器若回傳空檔案，用戶端可能保留舊設定，也可能回報解析結束但沒有節點。
訂閱本身由伺服器產生時，通常不建議長期手動修改下載檔案。下一次自動更新會覆蓋修改內容。需要保留本機 DNS、TUN 或規則設定時，應優先使用用戶端提供的覆寫、合併設定或腳本功能，並在每次用戶端升級後確認合併結果。
更新時使用直連還是代理
訂閱請求走哪一條路徑，是最容易被忽略的變數。訂閱網域可以直接存取時，使用直連最簡單，也不會依賴現有節點。訂閱網域只能透過代理存取時，則需要啟用用戶端的「透過代理更新」選項，或讓用戶端的更新器使用目前代理。不同用戶端對此選項的實作不同，有些使用系統代理，有些則直接呼叫目前的核心連接埠。
優先採用可啟動的更新路徑
如果訂閱更新必須依靠訂閱中的節點，就會形成啟動依賴：本機沒有可用的舊節點時，無法連線至訂閱伺服器；無法更新訂閱，又取得不到新節點。較穩妥的做法是保留最近一次可用的設定，並避免在更新失敗時清空本機檔案。
| 網路條件 | 建議更新路徑 | 原因 |
|---|---|---|
| 訂閱網域可直接存取 | 直連 | 降低對目前節點與代理連接埠的依賴 |
| 直連逾時，目前代理可存取 | 透過代理更新 | 避開本機網路連線至訂閱網站時的問題 |
| 啟用代理後反而更新失敗 | 暫時切回直連測試 | 排除節點故障、規則誤分流與代理驗證問題 |
| 新裝置尚無可用設定 | 使用服務方提供的直連入口 | 避免依賴尚未建立的代理連線 |
需要注意的是，訂閱管理請求未必會經過 Clash 規則。部分用戶端會在自身程序中直接下載訂閱，另一些則會將請求送至本機 mixed-port。即使規則中設定訂閱網域走 DIRECT，也不能保證用戶端更新器一定採用該規則。應以用戶端文件、更新設定與日誌中的實際連線路徑為準。
檢查本機連接埠與系統代理
常見設定會將 mixed-port 設為 7890，外部控制連接埠設為 9090，但這些只是常見值，並非固定要求。7890 被其他程序佔用時，系統代理仍可能指向舊連接埠，瀏覽器與訂閱更新器便會連線失敗。先在用戶端的「一般」或「網路」頁面確認目前的 HTTP、SOCKS 與 mixed 連接埠，再核對作業系統的代理位址是否一致。
TUN 模式的涵蓋範圍通常比系統代理更廣，但啟用 TUN 並不能修復失效連結、錯誤 UA 或 YAML 格式問題。若只有在 TUN 啟用時更新失敗，可以暫時關閉 TUN，保留系統代理後測試一次；再檢查 DNS 劫持、路由排除項目，以及訂閱網域是否被錯誤送入無法使用的策略群組。
自動更新間隔如何設定
自動更新不是越頻繁越好。節點與策略變更不頻繁的訂閱，每 6 小時更新一次通常已足夠；以秒為單位是 21600。變化較快且伺服器允許高頻請求的訂閱，可以設定為 1 小時，也就是 3600 秒。每天更新一次則是 86400 秒。低於 15 分鐘的頻率容易產生不必要的請求，也可能觸發 429 限流。
| 使用情境 | 建議間隔 | 秒數 |
|---|---|---|
| 一般個人使用，節點變化較少 | 6 小時 | 21600 |
| 節點經常調整，伺服器允許頻繁重新整理 | 1 小時 | 3600 |
| 設定長期穩定，只需定期同步 | 24 小時 | 86400 |
| 暫時排查期間 | 關閉自動更新，改用手動更新 | 避免錯誤請求反覆觸發 |
圖形用戶端通常會在訂閱編輯視窗提供更新間隔，單位可能是小時、分鐘或秒。修改前先查看欄位說明，不要將 3600 填入以「小時」為單位的輸入框。部分用戶端只會在程式執行期間計時；裝置休眠後，下一次更新可能在喚醒時立即執行。
mihomo 的 proxy-provider 更新範例
如果設定使用 proxy-providers，可以為每個提供器設定獨立的 interval。此值的單位是秒。以下範例每 6 小時擷取一次提供器檔案，並每 10 分鐘執行一次健康檢查。健康檢查與訂閱更新是兩套計時，不能互相取代。
proxy-providers:
service-a:
type: http
url: "https://sub.example.com/provider/demo-token"
path: ./providers/service-a.yaml
interval: 21600
health-check:
enable: true
url: "https://www.gstatic.com/generate_204"
interval: 600interval: 21600 控制遠端提供器檔案的重新整理週期；health-check.interval: 600 只控制節點可用性檢測。將健康檢查設為 600 秒，不會讓訂閱每 10 分鐘重新下載。反過來，訂閱更新成功也不代表每個節點都通過健康檢查。
依序完成一次完整排查
訂閱故障適合由外到內處理：先確認連結與伺服器回應，再檢查請求標頭與網路路徑，最後處理格式與本機載入。如此可以避免在連結已經失效時，反覆修改 DNS、TUN 與規則。
- 記錄錯誤時間。手動更新一次，立即查看日誌中的狀態碼、網域、逾時或解析錯誤。
- 確認連結完整。從伺服器重新複製 Clash 或 mihomo 類型的連結，在用戶端新增暫時訂閱。
- 測試直連回應。關閉「透過代理更新」後嘗試一次，並記錄結果。
- 測試代理回應。恢復一個已知可用的節點，啟用「透過代理更新」後再嘗試一次。
- 核對 User-Agent。只使用伺服器明確支援的識別，對比 403、200 與回應正文。
- 檢查內容格式。確認回應不是 HTML、錯誤 JSON、空檔案或不相容的 Base64 清單。
- 核對核心與欄位。查看 mihomo 或 Clash 核心版本，定位未知欄位、策略群組引用與 YAML 縮排問題。
- 重新載入設定。確認新檔案儲存成功，並在設定頁明確選取更新後的項目。
- 恢復合理間隔。一般情境設為 6 小時，頻繁變動情境設為 1 小時，並觀察是否出現 429。
更新成功後的驗證
更新完成後，不要只看綠色提示。先記錄節點總數與策略群組名稱，再選取一個節點執行延遲測試。接著造訪適合驗證出口位址的頁面，並在 Clash 連線紀錄中確認請求命中預期策略。若用戶端顯示更新成功，但節點清單與檔案修改時間都沒有變化，應檢查是否更新了尚未啟用的訂閱項目。
如果自動更新偶爾失敗、手動更新卻立即成功，常見原因包括裝置剛從休眠恢復、網路尚未就緒、代理核心晚於訂閱任務啟動，或伺服器短時間限流。可以適度延長更新間隔，並保留失敗日誌。若每次都在固定網路環境中失敗，則應重點比較直連、系統代理與 TUN 三種路徑，而不是繼續縮短重新整理週期。
最終穩定狀態應符合四項條件：訂閱連結有效、更新請求路徑明確、回傳內容與目前核心相容，以及自動更新頻率符合伺服器限制。分別確認這四項後，訂閱更新失敗通常就能定位到具體層級，不需要重新安裝用戶端或清空所有設定。