Clash 設定檔結構詳解:YAML 每一段字段的作用與寫法

設定檔總覽:YAML 語法基礎與頂層結構

Clash 與 Clash Meta(mihomo 核心)的設定檔都是一份 YAML 文字,通常命名為 config.yaml。訂閱連結背後其實也是同一份格式的檔案,客戶端下載後會把它儲存到本地目錄再解析載入。整份檔案按頂層鍵組織,常見的頂層鍵包括 port、socks-port、mixed-port、allow-lan、mode、log-level、dns、proxies、proxy-groups、rules,以及 Meta 核心特有的 tun。這些鍵處於同一縮排層級,誰也不包含誰,順序理論上不影響解析,但為了排查方便,大多數設定習慣把運作參數放最前,規則放最後。

YAML 靠縮排表達層級關係,不認 Tab 鍵,只認空格,且同一層級的縮排空格數必須完全一致。字串大多數時候不需要加引號,但如果值裡包含冒號、井字號或者以數字開頭卻要當字串處理,就應該加上英文引號。列表項用短橫線加空格開頭,字典項用冒號加空格分隔鍵值。這幾條規則看起來簡單,卻是後面所有錯誤的根源,建議在改設定前先記熟。

基礎運作段:埠、區域網路與運作模式

設定檔最上方一般是一組控制客戶端自身行為的字段,決定監聽埠、是否允許區域網路裝置接入,以及流量的處理模式。

port: 7890
socks-port: 7891
mixed-port: 7893
allow-lan: true
bind-address: "*"
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

• port:HTTP 代理監聽埠,系統代理設定裡填的就是這個值。
• socks-port:SOCKS5 代理埠,部分命令列工具或遊戲客戶端需要單獨設定這個協定。
• mixed-port:同一埠同時接受 HTTP 與 SOCKS5 請求,現在的圖形客戶端大多只用這一個埠,和 port/socks-port 可以只保留其一。
• allow-lan:是否允許同一區域網路內的其他裝置透過本機代理上網,預設為 false,給手機、平板共享代理時需要改成 true。
• mode:核心運作模式,rule 按規則分流是最常用的選擇,global 全域走同一個節點,direct 則完全不代理,只用於臨時偵錯。
• log-level:日誌詳細程度,排查問題時可以臨時改成 debug,日常使用建議保持 info 或 warning,避免日誌面板資訊過多影響查看。

DNS 段:字段含義與常見取值

dns 段控制網域解析的方式,設定得當能減少網域洩漏與解析延遲,設定不當則容易出現網頁打不開或者解析到錯誤位址的情況。一段常見寫法如下:

dns:
  enable: true
  ipv6: false
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.example-provider.net/dns-query
    - tls://dot.example-provider.net:853
  fallback:
    - https://fallback-doh.example-provider.net/dns-query
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"

• enable:是否啟用內建 DNS 伺服器接管解析,關閉後會退回系統本身的 DNS 設定。
• default-nameserver:用來解析 nameserver 裡那些 DoH/DoT 位址本身的網域,必須填純 IP,不能再填網域位址,否則會出現「解析伺服器的網域」這個先有雞還是先有蛋的問題。
• nameserver:實際用於解析日常網域的伺服器清單,支援傳統 UDP 位址,也支援 https:// 開頭的 DoH 與 tls:// 開頭的 DoT,加密解析能減少被電信業者劫持的機率。
• fallback:當 nameserver 判斷某個網域可能被汙染時,轉而使用的備用解析清單,常搭配 fallback-filter 一起使用。
• enhanced-mode:增強模式,fake-ip 會給網域分配一個虛構的內網位址再在出口還原成真實網域,相容性好也是大多數客戶端的預設值;redir-host 則是較舊的相容方案,一般不再建議使用。
• fake-ip-filter:排除在 fake-ip 之外的網域清單,區域網路裝置名稱、公司內網網域等建議加入這個清單,否則可能出現無法存取內網服務的情況。

proxies 段:節點字段怎麼填

proxies 是一個清單,每一項描述一個可用的代理節點,常見協定包括 ss(Shadowsocks)、vmess、trojan 以及 Meta 核心額外支援的 hysteria2。字段因協定不同略有差異,但都會包含名稱、伺服器位址、埠這三項基礎資訊。

proxies:
  - name: "範例-香港-01"
    type: ss
    server: node1.example-relay.net
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

  - name: "範例-日本-01"
    type: vmess
    server: node2.example-relay.net
    port: 443
    uuid: 11111111-2222-3333-4444-555555555555
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /path
      headers:
        Host: node2.example-relay.net

• name:節點在客戶端介面顯示的名稱,後面 proxy-groups 引用節點時靠這個名字比對,改名後要同步檢查分組裡的引用是否還對得上。
• type:協定類型,決定後面需要填哪些額外字段。
• server / port:節點伺服器位址與埠,直接從訂閱商提供的資訊裡取得。
• udp:是否為該節點開啟 UDP 轉發,遊戲連線、部分語音通話依賴 UDP,若客戶端支援建議保持開啟。
• tls / network / ws-opts:傳輸層與 TLS 相關設定,涉及 WebSocket 路徑、偽裝網域等,通常照抄訂閱商給出的參數即可,手動改動前建議先備份原始檔案。

絕大多數使用者不需要手寫這一整段——訂閱連結更新時,客戶端會自動重新產生這部分內容,手動編輯更多用於本地偵錯單個自建節點或者臨時修正某個字段的錯誤取值。

proxy-groups 段:分組類型與寫法

proxy-groups 決定節點如何被歸類展示,以及切換、測速的行為邏輯。每個分組至少要有 name、type、proxies 三項。

proxy-groups:
  - name: "自動選擇"
    type: url-test
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50
    proxies:
      - "範例-香港-01"
      - "範例-日本-01"

  - name: "節點選擇"
    type: select
    proxies:
      - "自動選擇"
      - "範例-香港-01"
      - "範例-日本-01"
      - DIRECT

  - name: "故障轉移"
    type: fallback
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    proxies:
      - "範例-香港-01"
      - "範例-日本-01"

• select:手動選擇型分組,介面上呈現為一個下拉清單,適合放在最外層給使用者手動切換。
• url-test:自動測速型分組,按 interval 設定的週期(單位秒)存取 url 測試延遲,自動選用延遲最低且優於 tolerance 容差範圍的節點。
• fallback:故障轉移型分組,按清單順序嘗試,目前節點不可用時自動切到下一個,適合對穩定性要求高於速度的情境。
• load-balance:負載平衡型分組,按策略把請求分攤到多個節點,適合多節點頻寬疊加的情境。

分組的 proxies 清單裡既可以填具體節點名,也可以填另一個分組的名字,還可以填 DIRECT(直連)或 REJECT(拒絕)這兩個內建策略名,這也是「節點選擇」分組裡嵌套「自動選擇」分組的常見寫法。

rules 段:規則語法與比對順序

rules 段是分流真正生效的地方,每一行格式固定為「規則類型,比對內容,目標策略」,自上而下逐條比對,命中第一條就停止,後面的規則不會再生效,所以順序很重要。

rules:
  - DOMAIN-SUFFIX,example-streaming.com,節點選擇
  - DOMAIN-KEYWORD,example-ads,REJECT
  - DOMAIN,api.example-tool.dev,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

• DOMAIN / DOMAIN-SUFFIX / DOMAIN-KEYWORD:分別是精確比對、比對網域後綴、比對網域中包含的關鍵字,後綴比對最常用,一條規則能覆蓋一個網域下的所有子網域。
• IP-CIDR / IP-CIDR6:按 IP 段比對,常用於把區域網路位址、內網位址直接放行,no-resolve 表示不對網域做額外解析,直接按目標 IP 判斷,可以減少不必要的 DNS 查詢。
• GEOIP:按目標 IP 所屬國家或地區比對,GEOIP,CN,DIRECT 是幾乎所有設定都會保留的一條,讓中國大陸位址直連,減少代理帶來的多餘繞行。
• MATCH:兜底規則,放在最後一行,代表前面所有規則都沒比對上的流量該怎麼處理,遺漏這一行會導致未命中的流量走向不確定。

規則裡出現的策略名必須和 proxy-groups 裡的 name 完全一致,包括大小寫與中文全形/半形字元,這是新手最容易忽略的細節之一——分組明明存在,規則卻提示策略不存在,往往就是名字打錯了一個字。

常見縮排與語法錯誤排查

手動改設定檔出錯,九成以上是縮排或標點問題,可以按下面的順序自查:

1. 檢查是否混用了 Tab 與空格,建議用文字編輯器把 Tab 統一替換成兩個或四個空格,並全文保持一致。
2. 檢查同一層級的清單項是否對齊,比如 proxies 下每一個 - name: 前面的空格數必須相同。
3. 檢查字串是否需要加引號,像 UUID、密碼裡包含冒號或者以數字開頭的字串,建議統一加上英文雙引號,避免被 YAML 解析成非字串類型。
4. 檢查規則行裡的逗號是否用了中文全形逗號,全形逗號在 YAML 裡不會被當作分隔符,規則會整體失效或報錯。
5. 如果一時定位不到具體哪一行出錯,可以把設定分段註解掉再逐段還原,快速縮小出錯範圍。

改完之後怎麼驗證

儲存設定後,大多數客戶端支援在介面上直接「重新載入設定」,不需要重啟整個程式。載入失敗時,客戶端一般會在日誌面板或者彈窗裡提示具體出錯的行號,對照上面的排查順序基本能找到問題。載入成功後,建議按以下幾點確認修改確實生效:

• 在代理頁面查看目標分組下的節點清單是否和剛才編輯的一致。
• 切換到日誌頁面,把日誌等級調到 debug,存取一個用於測試的網域,觀察是否命中了預期的規則和策略。
• 用命令列工具存取一個已知的偵測位址,確認回傳的出口資訊和預期節點一致,再把日誌等級改回日常使用的 info。