Clash 設定報錯速查：常見 YAML 錯誤與核心報錯對照

改完設定點儲存，用戶端彈一句英文報錯就沒了下文。這篇把常見報錯整理成對照表。

先做一次設定檢查

改設定之後、導入之前，用核心自己驗一遍：

mihomo -t -d /path/to/config/dir

-t 是 test 模式，只檢查不執行。它給出的錯誤資訊比用戶端彈出視窗詳細得多，通常直接告訴你第幾行有問題。

Clash Verge 使用者可以在設定目錄下對 config.yaml 執行這條命令。設定目錄位置：

一、YAML 語法錯誤

這類錯誤在設定解析阶段就失敗了，通常報錯裡帶行號。

found character that cannot start any token

原因：用了 Tab 縮進。YAML 只接受空格。

定位：編輯器裡打開「顯示空白字元」，Tab 會顯示成箭頭。

修複：全部替換成空格。VS Code 裡 Ctrl+Shift+P → 「Convert Indentation to Spaces」。

mapping values are not allowed in this context

原因：冒號後面缺空格，或者值裡有未加引號的冒號。

# 錯誤
port:7890
name: HK: 01

# 正確
port: 7890
name: "HK: 01"

did not find expected key / could not find expected ':'

原因：縮進層級不一致。

# 錯誤：兩個鍵縮進不同
proxies:
  - name: "A"
    type: trojan
     server: a.com      # ← 多了一个空格

# 正確
proxies:
  - name: "A"
    type: trojan
    server: a.com

found unexpected end of stream

原因：引號沒閉合，或者檔案被截斷。

檢查所有引號是否成對；如果設定是下載來的，可能沒下完整。

密碼裡的特殊字元

# 危險：# 會被當成註釋，@ 和 : 也可能出問題
password: p@ss#word

# 正確
password: "p@ss#word"

二、欄位與結構錯誤

語法沒問題，但核心不認識你寫的內容。

unmarshal error / cannot unmarshal !!str into int

原因：類型不對，比如連接埠寫成了字串。

# 錯誤
port: "443"      # 有些字段严格要求数字

# 正確
port: 443

反過來，UUID、密碼這類必須是字串：

uuid: 12345678-1234-1234-1234-123456789012      # 可能被解析成奇怪的类型
uuid: "12345678-1234-1234-1234-123456789012"    # 稳妥

unsupported proxy type: xxx

原因：訂閱裡用了當前核心版本不支援的協議。

修複：更新 Mihomo 核心。Clash Verge 裡：設定 → Clash 核心 → 更新。

如果更新後還是不支援，說明這個協議確實還沒被 Mihomo 實現，只能在服務商那邊換個協議的節點。

proxy 'xxx' not found

原因：策略組裡引用了不存在的節點名。

常見觸發：

• 手寫節點名時拼錯了
• 訂閱更新後節點改名了
• 擴充設定裡引用的策略組名和訂閱裡不一致（emoji、空格差異）

修複：打開訂閱原檔案，複製貼上準確的名字。或者改用 include-all + filter 自動收編，見節點分組正則。

rule 'xxx' error: invalid domain

原因：規則寫法有誤。

# 錯誤
- DOMAIN-SUFFIX,https://google.com,PROXY   # 不要写协议
- DOMAIN-SUFFIX,*.google.com,PROXY         # 不要写通配符
- IP-CIDR,8.8.8.8,DIRECT                   # IP-CIDR 必须带掩码

# 正確
- DOMAIN-SUFFIX,google.com,PROXY
- IP-CIDR,8.8.8.8/32,DIRECT,no-resolve

rules[N] [xxx] error: unsupported rule type

原因：規則類型名寫錯，或者核心版本不支援。

檢查拼寫：DOMAIN-SUFFIX 不是 DOMAIN_SUFFIX，IP-CIDR 不是 IPCIDR。

策略組循環引用

報錯：設定載入卡住或提示 recursive。

原因：A 組的 proxies 裡有 B，B 組的 proxies 裡有 A。

修複：理清層級，保證引用是單向的（上層組引用下層組，下層不反向引用）。

三、DNS 相關

default-nameserver 裡填了網域

# 錯誤
default-nameserver:
  - https://doh.pub/dns-query

# 正確：必須是純 IP
default-nameserver:
  - 223.5.5.5
  - 119.29.29.29

default-nameserver 的用途就是解析其他 DNS 伺服器的網域，所以它自己不能是網域。

解析不出內網網域

不是報錯，是行為不對。原因是 fake-ip 攔截了。

dns:
  fake-ip-filter:
    - "+.mycompany.com"
    - "*.lan"
    - "*.local"

詳見 DNS 設定詳解。

四、規則集與 provider

provider xxx: initial failed

原因：規則集或訂閱下載失敗。

排查：

規則集載入了但不生效

原因：behavior 和檔案內容不匹配。這個不會報錯，只是靜默失效。

rule-set xxx not found

規則集名在 rules 裡引用了，但 rule-providers 裡沒定義，或者名字拼錯了。

五、TUN 與權限

operation not permitted / TUN 開關點了沒反應

原因：權限不足，虛擬網路卡創建失敗。

修複：

• Windows / macOS：安裝「服務模式」
• Linux：sudo setcap cap_net_admin,cap_net_bind_service=+ep /path/to/mihomo

address already in use

連接埠被佔用。

# Windows
netstat -ano | findstr :7897
tasklist | findstr <PID>

# Linux / macOS
lsof -i :7897

改連接埠或停掉佔用的行程。

六、一個快速定位法

設定很長、報錯又沒給行號時，用二分法：

一個最小可用設定模板，用來做對照基線：

mixed-port: 7897
mode: rule
log-level: info
proxies:
  - name: "TEST"
    type: trojan
    server: example.com
    port: 443
    password: "pwd"
proxy-groups:
  - name: "PROXY"
    type: select
    proxies: ["TEST", DIRECT]
rules:
  - MATCH,PROXY

這份能載入，說明環境沒問題，問題在你的設定內容裡。

七、報錯速查表

八、預防措施

小結

• mihomo -t -d 目录 是最有用的一條命令，報錯比用戶端詳細
• YAML 三大坑：Tab 縮進、冒號後缺空格、引號沒閉合
• proxy not found 通常是名字對不上，從訂閱裡複製
• 規則集不生效但不報錯 = behavior 寫錯了
• 定位不了就用二分法砍設定

相關：YAML 結構詳解、Merge 擴充設定。

相關文件

設定基礎 Clash 設定檔 YAML 結構詳解：八個頂層欄位各管什麼

把一份 Clash / Mihomo 設定從頭到尾拆開講：連接埠、模式、DNS、proxies、proxy-groups、rules、rule-providers 的作用與寫法，附一份可直接使用的最小設定。

2026-08-021769 字約 4 分鐘

設定基礎 proxy-groups 五種類型詳解：select、url-test、fallback、load-balance、relay

每種策略組的實际行為、適用場景和關鍵參數，附帶一套可直接抄的分組結構，以及 Mihomo 特有的 include-all 與 filter 用法。

2026-07-291938 字約 5 分鐘

設定基礎 用 Merge 擴充訂閱設定，改了也不會被更新覆蓋

直接編輯訂閱檔案會在下次更新時前功盡棄。這篇講 Clash Verge 的擴充設定機制：prepend/append/override 的寫法、合併順序，以及幾個實用的擴充片段。

2026-07-091688 字約 4 分鐘