先理解訊息：YAML 能解析，不代表設定結構正確

yaml: unmarshal errors 通常表示程式把 YAML 文字轉成內部設定結構時，某個鍵或值無法放進預期欄位。它和「檔案完全不是 YAML」有關但不相同：有些檔案在一般 YAML 語法上成立，卻把字串欄位寫成清單、把布林欄位寫成物件，到 Mihomo 結構映射時才失敗。

先分成兩層。第一層是 YAML 語法與階層，例如 Tab、縮排、冒號後缺空格、引號未閉合；第二層是 Mihomo 結構，例如未知欄位、父層錯誤、值型別不符。Mihomo YAML 語法頁強調大小寫敏感、空格縮排、同層左對齊、冒號後空格與陣列短橫線。設定參考則用來確認欄位本身。

分開回答兩個問題：「是合法 YAML 嗎？」與「符合目前 Mihomo 版嗎？」一般 YAML 驗證通過只能回答前者。

不要看到錯誤就刪除訂閱或重裝客戶端。先複製原始檔，記錄完整錯誤、客戶端與核心版、設定來源和最近變更。更新後才出錯就保留前一版；手動編輯後出錯則先檢查本次差異。小範圍修正比重建整份設定更容易驗證。

從第一個行號處理，並查看父層與前一段

訊息可能是 line 42: cannot unmarshal ...，也可能一次列出多行。先處理第一條，因為前面的層級錯誤會讓後續欄位落入錯誤位置，產生連鎖訊息。行號常是解析器確認矛盾的位置，不保證筆誤就在該行；未閉合引號、上一段少縮排或錯誤清單起點可能更早。

  1. 建立只讀備份，不在唯一副本持續試錯。
  2. 以顯示行號、空白字元和 UTF-8 的純文字編輯器開啟。
  3. 定位第一條錯誤，向上查看同一父層與前一個清單項目。
  4. 把小段與官方欄位範例比較，不先格式化整份檔案。
  5. 只修一個確定問題，另存副本並重新驗證。

若該行包含節點機密，不要公開整行。保留欄位名和資料型別，把伺服器、UUID、密碼和訂閱參數換成占位符；但要保留空格數量和短橫線位置，否則失去層級證據。

訊息片段優先含義檢查範圍
did not find expected key鍵、引號或前段語法中斷本行與上方數行
cannot unmarshal !!seq into string字串欄位收到清單欄位文件與短橫線
cannot unmarshal !!map into bool布林欄位收到物件縮排與預期型別
field ... not found未知欄位、拼字或版本目前核心文件

編輯器的視覺換行不會改變真正行號，但聊天工具可能在貼上時轉換 Tab。應在原始純文字副本顯示不可見字元，再取最小且已脫敏的片段。

先修縮排、Tab、冒號與引號等語法問題

YAML 以縮排表示父子關係，不能用括號補救。官方語法說明要求使用空格而非 Tab、同層左側對齊、鍵的冒號後加空格，陣列項目從同層短橫線開始。兩格或四格可依檔案風格，但同一層必須一致。

下列錯誤例在項目前用了 Tab，且 type 沒和 name 對齊：

proxies:
	- name: Example
    type: ss

改成純空格並對齊同一代理物件：

proxies:
  - name: Example
    type: ss

mixed-port: 7890 的冒號後要有空格。URL、IPv6 或含 # 的文字在有歧義時依文件加引號，否則後段可能成為註解。引號必須成對，排版軟體的智慧引號不能替代 ASCII 引號。

不要全域重排空格：自動格式化可能改變多行文字、規則或腳本。只改已確認的結構範圍，保留原副本。

YAML 1.2.2 規格用來理解通用語法，Mihomo 文件則更接近實際欄位。先得到合法 YAML，再檢查設定型別。

語法通過後，檢查字串、數字、布林、物件與清單

cannot unmarshal 會提示來源與目標型別。!!seq 是清單，!!map 是鍵值物件，!!str 是字串，數字和布林也有各自型別。訊息不是叫你把所有短橫線刪掉，而是指出特定欄位收到與定義不同的結構。

例如把連接埠寫成帶引號字串，又把布林開關寫成清單：

mixed-port: "7890"
allow-lan:
  - true

依設定參考確認後應類似：

mixed-port: 7890
allow-lan: true

反過來，proxies、proxy-groups 和 rules 通常本來就是清單，不能為消除 !!seq 全部變成單一字串。每個欄位要分別對照目前版本。欄位名有大小寫與連字號要求；從舊核心或其他客戶端複製的鍵可能不存在或層級不同。

  • unknown field：查拼字、大小寫、版本與父層。
  • sequence into scalar：確認欄位接一值或多項。
  • map into scalar：檢查多一層縮排是否創造物件。
  • 重複鍵：不依賴覆蓋行為，合併成明確欄位。
  • null 或空值：依文件刪除、填有效值或保留空字串。

若問題來自遠端訂閱，不要長期改客戶端快取，更新會覆蓋。先確認服務商提供 Mihomo 格式；需本機調整時使用客戶端正式支援的覆寫機制。

使用最小變更與同版本核心驗證，再恢復完整內容

大型設定同時有節點、規則集、DNS、TUN 和腳本。修復方式是保留原件，對第一條錯誤做最小變動，而不是一次刪除所有可疑區塊。仍無法定位時，可在離線副本二分註解非必要段落；每次維持完整 YAML 層級並記錄移除範圍。

可用與客戶端相同版本、相同平台的 Mihomo 執行設定測試，常見形式如下，路徑要改成自己的脫敏副本：

mihomo -t -f /path/to/config.yaml

不要為驗證而從未知網站下載另一個核心。線上 YAML 工具可能上傳完整設定並洩漏憑證，且通常只能檢查通用語法。優先本機測試；需要求助時只分享最小復現片段。

  1. 為原始檔與最近可用版各留一份只讀副本。
  2. 只修第一個語法或型別錯誤，再執行同版檢查。
  3. 逐條處理剩餘訊息，不因數量多就整份重寫。
  4. 通過後由客戶端載入副本，先關閉系統代理與 TUN。
  5. 檢查設定、策略群組、DNS 日誌，再做一次實際連線。
  6. 穩定後才替換正式設定，並保留回復副本。

完成標準：設定檢查無錯誤、核心持續運作、預期群組存在、日誌沒有讀回舊檔，而且實際請求命中可解釋規則。只看到儲存成功不夠。

未知欄位仍存在時，向維護者提供核心版、第一條完整錯誤、已脫敏的父層與參考的官方文件。不要附訂閱 Token、伺服器密碼或整份正式設定。

官方來源與版本邊界

版本號、檔案名稱與介面文字可能隨專案更新而變動，操作前請以連結中的專案文件為準。