進階設定 預計閱讀 9 分鐘

Clash 配置檔 YAML 結構逐段解析:從連接埠設定到 rules 規則段

按 config.yaml 從上到下的順序講清每一段的作用:通用連接埠與模式、dns、proxies、proxy-groups、rules,標註常見縮排錯誤與欄位拼寫陷阱。

Clash 與 Clash Meta(mihomo)的核心配置檔都是一份 YAML 文件,習慣上命名為 config.yaml。它由若干頂層段落拼接而成,每一段各自負責一件事——連接埠和運行模式、DNS 解析方式、節點清單、策略組、分流規則。理解這幾段的先後關係與欄位含義,比死記某個「萬能配置」更有用,因為訂閱提供的遠端配置經常需要手動核對或合併本機設定,讀不懂結構就很容易改錯一個縮排導致整份檔案失效。本文按檔案從上到下的順序逐段拆解,並在每一段列出實際踩過的坑。

通用設定段:連接埠、模式與允許區域網路

檔案最上方通常是一批平鋪的鍵值對,負責定義用戶端本身的行為,與具體節點無關。常見欄位如下:

port: 7890
socks-port: 7891
redir-port: 7892
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

port 是 HTTP 代理連接埠,socks-port 是 SOCKS5 代理連接埠,兩者互不影響,可以同時開啟也可以只留一個。redir-port 用於透明代理情境,一般桌面使用者很少需要它。allow-lan 決定是否允許區域網路內其他裝置透過本機 IP 走代理,給手機或路由器共享上網時需要改成 true,同時要注意防火牆放行對應連接埠。

mode 有三個取值:rule 表示按規則段分流,global 表示所有流量強制走某個節點(常用於排查節點本身是否可用),direct 表示全部直連不走代理。日常使用應保持 rule,臨時測試節點連通性時才切到 global,測完記得切回來,否則會發現「明明配置了規則卻全部走了代理」這種誤會。external-controller 開啟後用戶端會暴露一個本機 API 連接埠,給 Dashboard 面板或第三方工具讀取運行狀態用,不需要這項功能的話可以留空或刪除該行。

dns 段:解析方式決定分流是否精準

dns 段控制網域解析行為,寫得不合適會直接影響規則分流的準確度,尤其是啟用 TUN 模式時。一段常見的寫法:

dns:
  enable: true
  ipv6: false
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.pub/dns-query
    - tls://dns.rubyfish.cn:853
  fallback:
    - https://1.1.1.1/dns-query
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - localhost.ptlogin2.qq.com

default-nameserver 是用來解析下面 nameserver 裡那些 DoH/DoT 位址本身的網域的伺服器,必須填純 IP,不能再填網域位址,否則會出現「解析伺服器的網域」這種循環依賴導致啟動報錯。nameserver 是真正對外提供解析的伺服器清單,fallback 是當 nameserver 判斷結果可能被污染時啟用的備用清單,常搭配 fallback-filter 按地理位置或回傳的 IP 段判斷。

fake-ip-range 與 TUN 模式配合使用,用戶端會給網域分配一個假 IP 段內的位址,再在流量層面還原真實網域去比對規則,這樣可以讓基於網域的分流規則在全域代理模式下依然生效。fake-ip-filter 裡列出的網域(比如內網網域、區域網路裝置名)不會被分配假 IP,而是走真實 DNS 解析,寫錯這一項常見後果是區域網路裝置(NAS、印表機、路由器管理頁)突然無法存取。

注意:如果不打算使用 TUN 模式,也不確定 fake-ip 的影響範圍,可以把 dns 段整體保持預設或直接沿用訂閱方給出的配置,不要隨意精簡欄位,DNS 設定錯誤往往表現為「某些網站能開某些不能開」,排查成本較高。

proxies 段:節點清單的欄位規範

proxies 是一個陣列,每個元素描述一個節點,欄位隨協定類型不同而不同。以最常見的 ss(Shadowsocks)和 vmess 舉例:

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example-node.invalid
    port: 8443
    cipher: aes-256-gcm
    password: "your-password-here"

  - name: "SG-02"
    type: vmess
    server: sg02.example-node.invalid
    port: 443
    uuid: 00000000-0000-0000-0000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /ws

幾個高頻出錯點:name 是給人看的識別碼,proxy-groups 引用節點時靠這個名字精確比對,改名之後如果沒同步改 proxy-groups 裡的引用,該節點就會在策略組裡「消失」;type 決定該條目後續欄位的解析方式,拼錯(比如把 vmess 寫成 vmes)會導致這個節點被整體忽略,通常用戶端不會報錯,只是節點清單裡少了一個,排查起來容易被忽略;password、uuid 建議加英文引號包裹,尤其密碼裡含有 :、# 等 YAML 特殊字元時,不加引號會被解析成別的結構導致節點整條失效。

如果節點由訂閱連結自動生成,proxies 段一般不需要手動編輯,用戶端會在匯入訂閱時自動填入;只有自建節點或手動新增單個節點時才會直接改這一段。

proxy-groups 段:把節點組織成可選擇的策略組

proxy-groups 決定使用者在用戶端介面上能看到、能切換的選項,以及規則段最終引用的分流出口。三種最常用的類型:

proxy-groups:
  - name: "自動選擇"
    type: url-test
    proxies:
      - HK-01
      - SG-02
    url: "http://www.gstatic.com/generate_204"
    interval: 300

  - name: "故障轉移"
    type: fallback
    proxies:
      - HK-01
      - SG-02
    url: "http://www.gstatic.com/generate_204"
    interval: 300

  - name: "節點選擇"
    type: select
    proxies:
      - 自動選擇
      - HK-01
      - SG-02
      - DIRECT

url-test 按延遲自動挑選目前最快節點,fallback 按清單順序優先使用第一個可用節點,select 是手動選擇,允許使用者在用戶端介面裡點選。注意 select 類型的 proxies 清單裡可以直接引用另一個策略組的名字(如上面的「自動選擇」),這是巢狀策略組的常見寫法,方便把「自動測速」包裝成「節點選擇」裡的一個選項。proxies 清單裡的名字必須與 proxies 段裡的 name 或另一個策略組的 name 完全一致,大小寫、全形半形字元都要對齊,寫錯一個字元會導致該策略組啟動時報錯或該選項被靜默剔除。

interval 是測速間隔,單位秒,數值過小會增加測速頻率、耗費額外流量與電量;url 建議用連通性判斷專用的偵測位址,不要填一般網站位址,否則測速結果可能被網站本身的回應速度干擾。

rules 段:分流規則的比對順序與寫法

rules 是檔案最後一段,也是逐行從上往下比對、比對到第一條就停止的段落,順序錯誤是最常見也最難自查的問題。基本語法:

rules:
  - DOMAIN-SUFFIX,google.com,節點選擇
  - DOMAIN-KEYWORD,github,節點選擇
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

每一行由「比對類型,比對內容,出口策略組」三段組成,部分類型還帶第四個可選參數(如 no-resolve 表示不對該規則做 DNS 解析,常用在 IP 段規則上以提升效率)。DOMAIN-SUFFIX 比對網域及其子網域,DOMAIN-KEYWORD 比對網域中包含的關鍵字,IP-CIDR 比對 IP 段,GEOIP 比對 IP 所屬國家/地區,MATCH 是保底規則,必須放在整個 rules 段的最後一行,代表「以上都不比對時走這裡」。

由於是順序比對,如果把一條寬泛規則(比如某個 GEOIP,CN,DIRECT)寫在具體規則前面,後面針對特定網域的規則永遠不會被觸發,表現為「明明配了某個網站走代理但實際沒生效」。正確的組織順序應該是:先寫具體的網域/應用程式規則,再寫寬泛的地區/IP 段規則,最後以 MATCH 收尾。

建議:規則數量較多時,可以把規則集拆分成遠端規則集(rule-providers)引用,減少手寫行數,同時便於統一更新,具體寫法可參考用戶端自帶的範例配置或官方文件中的 rule-providers 段說明。

常見縮排錯誤與欄位拼寫陷阱

YAML 對縮排極其敏感,以下幾類錯誤在實際使用中反覆出現:

  • 混用空格與 Tab:YAML 規範不允許用 Tab 縮排,文字編輯器如果自動把縮排轉成 Tab,用戶端會在啟動時直接報語法錯誤,建議用支援「以空格代替 Tab」的編輯器開啟配置檔。
  • 同層級欄位縮排不一致:同一個陣列元素內的欄位必須嚴格對齊同一列,哪怕多出一個空格也會被解析成子層級,導致該欄位被忽略或整個節點解析失敗。
  • 字串未加引號導致的類型誤判:密碼、UUID 中含有會被 YAML 當作特殊符號的字元(冒號、井號、方括號)時必須加引號,否則解析結果和預期不符。
  • 欄位名拼寫錯誤但不報錯:多數用戶端對未知欄位採取「忽略」而非「報錯」的策略,比如把 allow-lan 拼成 allow_lan,配置檔依然能正常載入,只是這項設定悄悄失效,排查時容易被忽略,建議改動關鍵欄位後重新檢查用戶端日誌或用官方範例核對欄位名。
  • proxy-groups 引用的節點名不存在:節點改名、刪除後沒有同步更新引用,策略組會缺一個選項甚至載入失敗,建議改動 proxies 段後用全文搜尋確認該節點名在 proxy-groups 裡的引用也同步更新。

把這幾段結構和常見坑點對照著看一遍配置檔,基本可以定位大多數「訂閱能匯入但規則不生效」「改了連接埠卻沒起作用」之類的問題。如果手動改動後用戶端無法啟動,優先檢查最近改動的那一段縮排,再確認欄位名拼寫與官方文件一致,通常問題就出在這兩類原因裡。

下載用戶端