先區分下載失敗與解析失敗
匯入訂閱通常會經過四個步驟：發出連結請求、接收回應、解析設定檔，再載入設定檔。介面顯示的「更新失敗」可能發生在任何一個步驟。找出失敗階段，才能判斷該更新連結、調整請求方式，還是檢查設定檔結構。
先保留目前可用的設定檔，再手動更新一次失敗的訂閱。開啟用戶端的「日誌」頁面，記下這次操作的時間、HTTP 狀態碼與第一則錯誤訊息。各用戶端的選單名稱不盡相同，重點是找到訂閱更新日誌，而不是連線測速結果。
| 日誌線索 | 所處階段 | 優先檢查項目 |
|---|---|---|
no such host |
網域解析 | 訂閱網域是否正確，以及目前 DNS 是否可用 |
timeout 或 connection refused |
建立連線或讀取回應 | 網路路徑、代理連接埠、伺服器是否可連線 |
| HTTP 401、403、404、410 | 伺服器回應 | 授權、存取限制，以及連結是否已變更 |
yaml: 與行號 |
解析回應內容 | 回應是否為設定檔，以及縮排和資料型別是否正確 |
proxy not found |
設定檔引用檢查 | 策略群組、節點與規則目標名稱是否相符 |
連結過期與帳戶狀態
重新複製完整的訂閱網址
前往服務提供者的帳戶頁面，重新複製適用於 Mihomo 的訂閱網址。請勿將帳戶登入頁、購買頁或瀏覽器網址列中的控制台網址誤當成訂閱連結。複製後檢查是否混入空格、換行或中文標點，並確認 ? 後的參數沒有被通訊軟體截斷。
- 401：通常表示缺少有效的驗證資訊，請先確認連結權杖與帳戶狀態。
- 403：可能是授權遭拒，也可能受到請求標頭、地區、IP 或風控機制限制，不能只憑狀態碼判定訂閱已到期。
- 404 或 410：可能是入口已移動、連結遭撤銷或資源已移除，請回到帳戶頁面確認。
- 429：表示請求過於頻繁，請依照回應中的
Retry-After等待，不要連續點選更新。 - 5xx：優先確認伺服器狀態，稍後再試，避免一開始就大幅修改本機設定。
流量用罄、方案到期與權杖失效是不同情況。部分服務會回傳空清單或說明文字，而非明確的 401。請一併查看回應本文與帳戶狀態，不能只看「請求成功」。
瀏覽器驗證的限制
在可信任的裝置上直接開啟訂閱連結，可初步判斷回應是登入頁、錯誤頁還是檔案下載。不過，瀏覽器可能會帶上登入 Cookie，也可能使用與用戶端不同的 User-Agent。瀏覽器能下載，不代表用戶端一定能取得相同內容；瀏覽器顯示亂碼，也不代表設定檔已損毀。
如果連結回傳登入表單或驗證碼頁面，請先確認複製的是專用訂閱入口。不要將網頁另存為 .yaml 再匯入。瀏覽器測試會留下瀏覽紀錄，在共用裝置上尤其要小心。
檢查 HTTP 回應與實際內容
光看副檔名無法判斷檔案內容。名為 config.yaml 的回應可能其實是 HTML；HTTP 200 也可能只代表收到「訂閱已失效」的提示。請一併檢查狀態碼、重新導向情形與本文開頭。
使用 curl 留下可供比對的結果
以下指令適用於已安裝 curl 的 macOS 或 Linux Bash 終端機。輸入連結時不會顯示在畫面上，也不會直接寫入命令歷史；但請求執行期間，展開後的網址仍可能被本機具有相應權限的程序看到。輸出檔案也可能包含憑證，請只保存在本機。
read -r -s -p '訂閱網址：' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
--connect-timeout 10 --max-time 30 \
--dump-header subscription-headers.txt \
--output subscription-response.txt \
--write-out 'HTTP %{http_code}\n' \
"$SUB_URL"
unset SUB_URL這裡將連線逾時設為 10 秒、整個請求的上限設為 30 秒，最多跟隨 5 次重新導向。這些只是排查參數，並非服務效能的實測結果。請勿加上 -k 略過憑證驗證，也不要使用 --location-trusted 將驗證資訊傳給重新導向的目標。
- 查看終端機中的 curl 錯誤與最終 HTTP 狀態。若尚未收到 HTTP 回應就已連線失敗，可能會顯示
000；這不是伺服器狀態碼。 - 查看
subscription-headers.txt。跟隨重新導向時，檔案中可能有多段回應標頭，請找到最後一段。 - 在本機文字編輯器中開啟
subscription-response.txt，確認開頭是設定欄位、編碼後的節點清單，還是 HTML 或錯誤說明。 - 確認重新導向的目標是否為服務提供者認可的網域。請勿公開回應標頭，其中可能含有 Cookie 或附帶權杖的網址。
Content-Type 只能作為線索，不能做為最終判斷依據。有些服務會將 YAML 標示為 text/plain，仍可正常使用；反過來說，回應標頭標示為 YAML，也不代表本文的語法與結構一定正確。
區分完整設定檔、節點集合與編碼訂閱
「回傳內容是 YAML」只完成了一半的檢查。Mihomo 完整設定檔、proxy-providers 使用的節點集合，以及 URI 或 Base64 節點訂閱，是不同類型的輸入。用戶端是否負責轉換這些內容，取決於個別實作，不能假設所有用戶端都支援自動轉換。
| 內容特徵 | 常見用途 | 常見誤用 |
|---|---|---|
| 包含代理來源、策略群組與規則 | 做為完整設定檔載入 | 引用不存在的節點或策略群組 |
以 proxies: 為主體的節點集合 |
供 proxy-providers 引用 |
誤以為包含所有策略與分流規則 |
多行 ss://、vmess:// 等連結，或其編碼文字 |
交由支援該格式的匯入工具轉換 | 直接做為核心 YAML 設定檔載入 |
<!DOCTYPE html> 或 <html> |
網頁內容或存取遭封鎖時的回應 | 只修改副檔名為 YAML，試圖修復內容 |
YAML 行號與欄位型別
日誌指出第 18 行，不一定表示第 18 行本身有問題；上一行缺少冒號或引號未關閉，也可能讓解析器到下一行才報錯。請檢查錯誤行前後至少各 3 行，並使用空格縮排，避免混用 Tab。
# 結構示意，並非可直接連線的完整設定檔
proxies: []
proxy-groups:
- name: 手動選擇
type: select
proxies:
- DIRECT
rules:
- MATCH,手動選擇這個範例用來檢查清單與縮排結構，不含代理節點。實際設定檔還必須確保規則目標、策略群組名稱與節點名稱完全相符。中文標點、尾端空格及大小寫差異，都可能導致引用失敗。
區分語法正確與核心支援
YAML 語法正確，不代表目前的核心支援其中的協定、傳輸方式或欄位。請先在用戶端的「關於」或核心資訊頁記下實際核心版本，再確認該版本支援的範圍。用戶端版本和核心版本並非同一概念。
若需要進一步定位問題，可在權限受限的目錄中儲存完整設定檔，使用本機 Mihomo 執行 mihomo -t -f config.yaml 測試設定。這不等於測試網路連線是否可用；若涉及外部資源，也要檢查資源載入日誌。未審核的設定檔請勿直接啟用服務。
User-Agent 與訂閱回傳格式
部分訂閱服務會依據 User-Agent 判斷要回傳哪種設定。同一個網址在瀏覽器中回傳說明頁，用戶端卻收到 YAML，或情況相反，可能與此機制有關。請優先使用服務提供者明確標示的 Mihomo 訂閱入口，不要一開始就隨意修改請求標頭。
- 保持網址、網路與測試時間相近，只變更 User-Agent，避免同時改動多個變數。
- 先記下用戶端日誌中可確認的請求資訊，再查閱服務提供者文件指定的 User-Agent 值。
- 使用 curl 的
--user-agent進行對照，分別儲存兩次結果，比較狀態碼與本文結構。 - 確認結果後，再檢查用戶端是否允許為訂閱請求單獨設定該請求標頭。不要只修改瀏覽器設定。
例如，若服務提供者明確支援此識別值，可以測試 --user-agent 'clash.meta'。這不是所有訂閱服務通用的修復值，也不保證回傳的設定與目前核心相容。如果回應仍是登入頁或 403，應繼續檢查授權與網路限制，而不是不斷更換識別值。
網路、DNS 與代理更新路徑
瀏覽器能連線，用戶端卻逾時
先確認請求是否走相同的網路路徑。瀏覽器可能使用系統代理，用戶端的訂閱更新元件則可能直接連線、使用內建代理，或採用另外設定的下載路徑。啟用系統代理，不代表每個程序都會自動使用。
如果用戶端提供「透過代理更新訂閱」之類的選項，請先確認目前的代理可用。若訂閱已失效，節點也無法連線，強制透過舊節點更新可能形成依賴循環。請保留一份可用設定檔，再依服務提供者支援的方式嘗試其他網路路徑。
- DNS：
no such host請先檢查網域拼字與系統解析；不要直接將可能變動的服務 IP 寫死。 - 代理連接埠：若本機 HTTP 代理設定為
127.0.0.1:7890，請確認用戶端實際監聽此連接埠。7890 僅為範例，並非所有用戶端的預設值。 - TUN：TUN 可能會改變程序的流量路徑，但無法修復錯誤的 YAML。切換前先記下目前的開關狀態，測試後再恢復，避免混淆兩類問題。
- TLS：若出現憑證錯誤，請檢查系統日期、時區、訂閱網域與網路驗證頁面，不要直接關閉憑證驗證。
使用不同網路進行對照測試
情況允許時，分別透過手機熱點與原本的網路發出一次請求。保持連結與 User-Agent 不變。如果只有其中一個網路回傳 HTML 封鎖頁或連線逾時，排查重點應轉向網路路徑；如果兩邊都穩定回傳相同的格式錯誤，則應回頭檢查訂閱內容與用戶端相容性。
curl 的 --noproxy '*' 可排除 curl 層級的明確代理設定，但無法繞過系統 TUN、路由規則或網路出口設備。因此，「使用這個參數後仍失敗」不能直接證明直連路徑有問題。
恢復匯入與提供最少必要資訊
修改後先手動更新一次，確認設定檔已通過解析，再切換至新設定檔測試連線。訂閱更新成功只代表內容已收到並處理，不表示所有節點都可用，也不代表 DNS、系統代理與規則分流都已設定完成。
- 確認訂閱更新時間、節點數量，以及預期的策略群組是否存在。
- 查看載入日誌，確認沒有節點類型不支援、提供器下載失敗或規則目標不存在等錯誤。
- 連線到已知可存取的測試目標，查看連線日誌中的符合規則、策略群組與出口。
- 保留舊設定檔以便還原，確認新設定檔穩定後，再清除暫存的回應檔案。
仍然失敗時，應提供哪些資訊
向用戶端維護者或訂閱服務提供者回報時，請附上作業系統、用戶端版本、核心版本、失敗時間、HTTP 狀態碼、已遮蔽敏感資訊的第一則錯誤，以及直連與代理更新的對照結果。若是格式問題，可提供保留縮排的最小片段，請勿提交完整訂閱連結或節點憑證。
排查順序可整理為：先確認連結與授權，再查看回應本文，接著核對格式與核心支援，最後比較請求標頭和網路路徑。每次只調整一個變數，可減少因「偶爾成功」造成的誤判，也更容易在之後更新訂閱時重現並修復同類問題。