本文目錄
匯入訂閱時出現一長串錯誤，不必立刻編輯檔案。請求可能沒有取得設定，也可能已取得內容卻無法載入，兩者的下一步完全不同。保留完整錯誤訊息與可用副本，再判斷回傳內容是否適合目前的核心，修復時也更容易還原原本狀態。
訂閱失敗在下載階段，還是設定解析階段？
儲存錯誤原文、HTTP 狀態與具體行號，依下表區分下載問題與設定解析問題。連結失效或回傳登入頁時，檢查訂閱來源；縮排錯誤或核心不支援欄位時，才檢查已下載的內容。
兩類失敗的證據
| 表現 | 說明 | 先做什麼 |
|---|---|---|
| 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。截圖和日誌遮住完整位址中的憑據，無法判斷時遮住整個 URL；curl 命令不要貼入公開工單。連結已暴露時，先在服務管理介面重設，再繼續排查。
# URL 中含私密 token，不要复制输出到公开位置
curl -I "https://example.invalid/subscription?token=REDACTED"
curl -sS "https://example.invalid/subscription?token=REDACTED" | head服務可能依請求的 User-Agent 傳回不同內容；以用戶端實際更新時的回應為準。curl 結果只作比對，不能單憑它判定訂閱連結失效。
縮進錯誤與核心欄位不相容的處理
YAML 用縮進表達層級，Tab、漏掉的冒號、未閉合引號和錯誤的清單橫線都可能讓解析器在下一行才發生錯誤。看到 line 48 column 7，不只看第 48 行，還要向上檢查它屬於哪個鍵、上一項是否結束。
代理名含冒號、井號或特殊字元時應使用引號；同一層不要混用不同數量的空格。編輯副本並保留原檔案，每次只修正一個錯誤，重新測試後再看下一條。
# 正确：proxies 是列表
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
# 错误：proxies 被写成普通字符串
proxy-groups:
- name: PROXY
type: select
proxies: DIRECT通用 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 或服務方重新產生的乾淨訂閱，讓網路恢復。不要在日常使用的唯一設定上連續手動修改，也不要把解析失敗的檔案設為開機自動載入。
修復記錄至少保留失敗階段、原始錯誤、用戶端與核心版本、解決動作。下一次同一訂閱更新後再次出現時，這些資訊能判斷是伺服器端產生變化、用戶端升級還是本機覆寫重新引入了錯誤。