Clash 設定檔 YAML 結構逐段解析:通用欄位、proxies、proxy-groups 與 rules

設定檔整體結構與閱讀順序

Clash 的 config.yaml 是 YAML 格式的文字檔,客戶端啟動時會依序讀取頂層欄位。理解它的最佳方式,是把檔案從上到下分成四段:通用設定、DNS 設定、節點定義、策略組與規則。

YAML 的語法約束很直接:縮排用空格(禁止 Tab),同層欄位縮排必須一致,鍵與值之間用英文冒號加空格分隔。欄位順序本身不影響解析,但 proxies、proxy-groups、rules 之間存在引用關係:策略組引用的節點名稱必須先在 proxies 裡定義,規則引用的策略組名稱必須先在 proxy-groups 裡定義。按照「通用 → DNS → proxies → proxy-groups → rules」的順序撰寫,既符合閱讀直覺,也能避免引用未定義名稱的報錯。

一個最小可用設定的骨架:

port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info

dns:
  enable: true
  nameserver:
    - 223.5.5.5

proxies:
  - name: "範例節點"
    type: ss
    server: 203.0.113.10
    port: 443
    cipher: aes-256-gcm
    password: "example-password"

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - "範例節點"
      - DIRECT

rules:
  - DOMAIN-SUFFIX,github.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

這個骨架省略了 ipv6、external-controller 等選用欄位,但已經能完成「啟動 → 走代理 → 規則分流」的完整流程。

通用欄位:連接埠、模式與日誌

頂層通用欄位控制客戶端的基本行為,下表列出最常用的幾個:

mode 是三個取值最容易混淆的欄位。rule 模式會依 rules 區規則逐條比對,命中即轉發,這是日常使用最常見的模式;global 模式讓所有流量都走 proxy-groups 裡第一個策略組,跳過 rules 比對;direct 模式讓所有流量直連,相當於全域繞過代理,適合用來排查節點故障。

port 與 socks-port 可以同時監聽,也可以只開其中一個。如果本機 7890 被其他程式占用,啟動日誌會提示 bind: address already in use,把連接埠改成 7897 之類未占用的值即可。

external-controller 提供 RESTful API,Clash Verge 的面板、Yacd、Metacubexd 都透過這個位址讀取與修改設定。預設綁定 127.0.0.1 只允許本機存取;如果設定了 secret 欄位,存取 API 時需要帶上對應的請求標頭。

log-level 建議日常用 info,排查問題時暫時切到 debug。debug 會輸出每條連線的規則命中資訊:

[TCP] dial Match(DomainSuffix): github.com → PROXY
[UDP] dial Match(GEOIP): 8.8.8.8 → DIRECT

這類日誌能直接告訴你流量被哪條規則接走,是除錯分流最有效的著手點。

DNS 設定段:nameserver 與 fallback 的分工

dns 段決定網域名稱解析走哪條路徑,是設定裡第二重要的部分。核心欄位如下:

nameserver 負責解析大多數網域,一般填中國大陸公共 DNS,例如 223.5.5.5(阿里雲)與 119.29.29.29(騰訊雲),回應快且沒有污染問題。

fallback 用於處理被污染的網域:當 nameserver 回傳的 IP 被 geoip 判定為保留位址時,客戶端會用 fallback 裡的伺服器重新解析一次。簡單情境下,把 fallback 填成 8.8.8.8 與 1.1.1.1 即可。

這裡有一個容易踩的坑:如果 proxies 裡的節點使用網域而非 IP,客戶端解析節點網域時也會走 dns 段。一旦節點網域被污染,所有節點都會連不上。所以 default-nameserver 必須填一個可靠的中國大陸 DNS,並且不要把節點網域解析交給 fallback 流程。TUN 模式下,dns 段的 enable 必須為 true,否則開啟 TUN 後系統流量無法正確解析網域。

proxies 節點:每種協定怎麼定義

proxies 是一個陣列,每個元素定義一個代理節點。不同協定共用 name、type、server、port 四個基礎欄位,協定專屬欄位則各不相同。

SS 節點的欄位最少:

- name: "SS-東京"
  type: ss
  server: 203.0.113.10
  port: 443
  cipher: aes-256-gcm
  password: "your-password"

cipher 常見取值有 aes-256-gcm、chacha20-ietf-poly1305、2022-blake3-aes-256-gcm 等。密碼必須與訂閱服務商提供的一致,否則握手階段會直接失敗。

VMess 節點多了 uuid、alterId 與傳輸層欄位:

- name: "VMess-新加坡"
  type: vmess
  server: 203.0.113.20
  port: 443
  uuid: "550e8400-e29b-41d4-a716-446655440000"
  alterId: 0
  cipher: auto
  network: ws
  ws-opts:
    path: "/path"
    headers:
      Host: "example.com"

alterId 在較新的服務端實作裡通常為 0。network 為 ws 時必須搭配 ws-opts 的 path 與 Host 使用,兩者要與訂閱服務商的設定一一對應,填錯會導致 TLS 握手後無法建立隧道。

Trojan 節點結構與 VMess 類似,但沒有 uuid:

- name: "Trojan-洛杉磯"
  type: trojan
  server: 203.0.113.30
  port: 443
  password: "your-password"
  sni: "example.com"
  skip-cert-verify: false

sni 用於 TLS 的 SNI 擴充,必須與憑證網域一致。skip-cert-verify 預設為 false,不建議改成 true,除非節點憑證本身不合法且你確認風險可接受。

Hysteria2 節點額外需要 up 與 down 頻寬參數:

- name: "Hysteria2-香港"
  type: hysteria2
  server: 203.0.113.40
  port: 443
  password: "your-password"
  up: "50 Mbps"
  down: "200 Mbps"
  sni: "example.com"

up/down 宣告客戶端可用頻寬,數值偏小會限制傳輸速度,偏大可能導致壅塞。

proxy-groups 策略組:選擇邏輯如何嵌套

proxy-groups 定義策略組,組內 proxies 列表可以引用節點,也可以引用其他策略組。四種常用類型:

select 類型最直觀:

- name: PROXY
  type: select
  proxies:
    - "SS-東京"
    - "VMess-新加坡"
    - "Trojan-洛杉磯"
    - DIRECT
    - REJECT

url-test 需要額外設定測速位址與間隔:

- name: Auto
  type: url-test
  url: "https://www.gstatic.com/generate_204"
  interval: 300
  tolerance: 50
  proxies:
    - "SS-東京"
    - "VMess-新加坡"

interval 單位是秒,300 表示每 5 分鐘測一次速。tolerance 表示延遲差小於 50ms 時不切換,避免頻繁抖動。

策略組可以嵌套,這是進階寫法:

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Auto
      - "SS-東京"
      - DIRECT
  - name: Auto
    type: url-test
    proxies:
      - "SS-東京"
      - "VMess-新加坡"

這裡 PROXY 組的第一個選項是 Auto 組,選中 Auto 後實際流量由 url-test 自動決定。嵌套層數沒有硬性限制,但建議不要超過兩層,否則排查「目前走的是哪個節點」會變得困難。

rules 規則區:比對順序決定流量走向

rules 是最後一節,也是流量分流的核心。Clash 會依序逐條比對,命中第一條就停止,不再繼續往下看。因此規則順序非常關鍵。

常用規則類型:

一個可用於正式環境的 rules 範例:

rules:
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT
  - DOMAIN-SUFFIX,cn,DIRECT
  - GEOIP,CN,DIRECT
  - DOMAIN-SUFFIX,google.com,PROXY
  - DOMAIN-SUFFIX,youtube.com,PROXY
  - DOMAIN-KEYWORD,github,PROXY
  - MATCH,PROXY

注意上面這個順序:區域網路與中國大陸流量先被 DIRECT 接走,再比對國外網域走 PROXY,最後 MATCH 兜底。如果把 DOMAIN-SUFFIX,google.com,PROXY 放到 GEOIP,CN,DIRECT 前面,google.com 的解析結果如果是中國大陸 IP(例如被 CDN 調度到中國大陸節點),就會錯誤地直連。

規則名稱(最後一個欄位)必須是 proxy-groups 裡定義的組名,或是 DIRECT、REJECT 這兩個內建目標。引用不存在的組名,設定校驗會直接報錯。

校驗設定與常見錯誤

寫完 config.yaml 後,先用命令列校驗語法,再啟動客戶端,能省下大量排查時間。mihomo 核心的校驗命令:

./mihomo -t -f config.yaml

輸出 configuration file ... test is successful 表示通過。Clash Verge 的「設定」→「參數設定」裡也提供設定檢查入口,本質上呼叫的是同一條校驗邏輯。

常見錯誤依出現頻率排序:

1. 縮排用了 Tab。YAML 只認空格,在編輯器裡勾選「將 Tab 轉為空格」即可避免。
2. 冒號後漏空格。port:7890 會被解析成字串鍵,而不是連接埠欄位。
3. 密碼等特殊字元未加引號。密碼含 #、:、* 等字元時必須用雙引號包裹,否則 YAML 會把它當成註解或結構符號。
4. 引用了未定義的節點名稱或策略組名稱。檢查 proxies 的 name 與 proxy-groups 的 proxies 列表是否完全一致。
5. 重複定義同名節點。後一個定義會覆蓋前一個,容易造成「改了設定但行為沒變」的假象。

把校驗命令的輸出與上面這張清單對照,絕大多數設定問題都能在 5 分鐘內定位。