本文目錄
Clash 訂閱匯入失敗，先分清連結失效還是格式讀不懂
用戶端常把「更新失敗」顯示成一條通知，但連結失效、Invalid YAML 和 unsupported field 需要完全不同的處理。保留錯誤原文、HTTP 狀態和行號，先判斷失敗階段，才不會拿 YAML 編輯器修一份實際是登入頁面的檔案。
兩類失敗的證據
| 表現 | 說明 | 先做什麼 |
|---|---|---|
| HTTP 401、403、404、超時 | 遠端請求還沒得到可用設定 | 檢查 token、位址、網路和伺服器端狀態 |
| 回傳 HTML、登入頁或方案提示 | URL 能存取，但內容不是 YAML | 確認複製的是訂閱介面而非網頁位址 |
| mapping values are not allowed | YAML 結構或縮進錯誤 | 按發生錯誤行和上一層縮進定位 |
| unknown field、cannot unmarshal | 語法可能成立，但欄位或資料類型不被目前核心接受 | 核對核心版本和官方欄位 |
查看回傳頭和開頭內容，不公開完整訂閱位址
在自己控制的終端或瀏覽器開發工具中查看訂閱回應。狀態應成功，正文開頭應像 YAML 設定或 provider 資料，而不是 <!DOCTYPE html>、登入表單、JSON 錯誤或「流量已用完」的提示。
訂閱 URL 常含可直接拉取設定的 token。截圖時遮掉查詢參數，curl 命令不要粘進公開工單；如果連結已經暴露，先到服務面板重置，再繼續檢查舊回應。
# URL 中含私密 token，不要复制输出到公开位置
curl -I "https://example.invalid/subscription?token=REDACTED"
curl -sS "https://example.invalid/subscription?token=REDACTED" | headYAML 發生錯誤行常常只是上一層結構已經壞了
YAML 用縮進表達層級，Tab、漏掉的冒號、未閉合引號和錯誤的清單橫線都可能讓解析器在下一行才發生錯誤。看到 line 48 column 7，不只看第 48 行，還要向上檢查它屬於哪個鍵、上一項是否結束。
代理名含冒號、井號或特殊字元時應使用引號；同一層不要混用不同數量的空格。編輯副本並保留原檔案，每次只修一個發生錯誤，重新測試後再看下一條。
# 正确：proxies 是列表
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
# 错误：proxies 被写成普通字符串
proxy-groups:
- name: PROXY
type: select
proxies: DIRECTYAML 能解析，不代表 Mihomo 接受這些欄位
通用 YAML 檢查器只驗證文字結構，不知道 Mihomo 的欄位、類型和引用關係。unknown field、proxy not found、group not found 或不支援的協議，說明要回到目前核心文件與版本，而不是繼續調整縮進。
用戶端內建的核心版本可能落後於訂閱產生器，也可能因合併覆寫把欄位移到錯誤位置。先在「關於」或啟動日誌中確認實際核心，再對照目前 Mihomo 文件；升級前保留可用設定，避免把協議相容問題變成新的遷移問題。
完整設定、節點 Provider 和規則集不能互相頂替
完整設定通常包含連接埠、代理群組和 rules；proxy-provider 檔案主要提供節點；rule-provider 檔案則按 domain、ipcidr 或 classical 等行為提供規則內容。
如果把 provider URL 當成完整訂閱匯入，即使檔案本身是合法 YAML，用戶端仍會提示缺少完整設定所需的欄位。
反過來，把完整設定填進 proxy-providers，也可能在解析清單時失敗。先看回傳頂層鍵和服務方提供的匯入方式，再決定它應放在 Profile、proxy-providers 還是 rule-providers。
- 完整 Profile
- 通常能獨立載入，含 proxy-groups 與 rules 等執行設定。
- Proxy Provider
- 供主設定的 proxy-providers 引用，內容重點是節點清單。
- Rule Provider
- 供 RULE-SET 使用，behavior 與 payload 結構必須對應。
在副本裡測試，還要看用戶端合併後的最終檔案
先儲存原始回應副本，把 token 與節點認證資訊遮蔽後再編輯。Mihomo 命令列可用設定測試功能檢查指定目錄，圖形用戶端也通常在載入前執行驗證；以目前實際核心輸出的第一條錯誤為準。
若原檔案能透過、用戶端仍失敗，查看 Merge、Mixin、覆寫指令碼或全域設定產生的最終設定。常見問題不是訂閱本身壞了，而是覆寫引用了已經刪除的策略群組，或把同一個頂層鍵產生了兩份不相容內容。
原始訂閱可讀，最終設定報 group not found
常見原因：覆寫或舊規則引用已不存在的策略群組
處理方法：在最終設定搜尋組名，暫時停用相關覆寫。
訂閱是 HTML
常見原因：複製了網站頁面、登入已過期或 token 失效
處理方法：重新取得專用訂閱位址，不編輯 HTML。
Provider 單獨更新失敗
常見原因：URL、path、behavior 或寫入權限問題
處理方法：按 provider 類型檢查，不重做整個 Profile。
先恢復一份能載入的設定，再整理錯誤原因
正在使用的設定損壞時，先切回上一份可用 Profile 或服務方重新產生的乾淨訂閱，讓網路恢復。不要在唯一的生產設定上連續手改，也不要把解析失敗檔案設為開機自動載入。
修復記錄至少保留失敗階段、原始錯誤、用戶端與核心版本、解決動作。下一次同一訂閱更新後再次出現時，這些資訊能判斷是伺服器端產生變化、用戶端升級還是本機覆寫重新引入了錯誤。