進階設定 預計閱讀 13 分鐘

Clash YAML 設定檔各段欄位解析

依設定檔書寫順序，說明從 port、mode、dns 到 proxies、proxy-groups、rules 的欄位用途、可用值與常見設定錯誤。

Clash 設定檔通常使用 YAML 撰寫，會將監聽連接埠、運作模式、DNS、代理節點、策略群組與分流規則放在同一份文件中。欄位排列順序通常不影響核心讀取，但依照「基礎參數 → DNS → 節點 → 策略群組 → 規則」的順序撰寫，更容易找出引用關係與縮排錯誤。

本文以 Clash for Windows 0.20.39 常見設定結構，以及 mihomo v1.19 系列的設定語意為參考。不同核心支援的協定、TUN 參數與 DNS 擴充欄位不完全相同。修改訂閱產生的設定前，建議先另存本機副本，避免下次更新訂閱時覆蓋手動修改的內容。

YAML 語法與頂層結構

縮排、清單與鍵值

YAML 使用空格表示層級，不能用 Tab 取代縮排。常見做法是每層縮排 2 個空格。冒號後要保留一個空格，清單項目則以短橫線開頭。節點、策略群組與規則位於不同的頂層鍵下，層級只要錯一格，就可能導致整份檔案無法載入。

port: 7890
mode: rule

proxies:
  - name: "範例節點"
    type: ss
    server: 203.0.113.10
    port: 443

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

rules:
  - MATCH,節點選擇

port: 7890 是一組鍵值；proxies: 後方是清單；每個以 - name: 開頭的項目都是一個節點物件。包含冒號、井字號、星號，或容易被判讀為布林值的名稱，最好加上引號。例如將節點名稱寫成 "HK: 01"，可避免冒號被當成映射分隔符。

常見解析錯誤

連接埠、區域網路與運作模式欄位

檔案開頭通常是入站監聽與基礎運作參數。以下範例分別為 HTTP、SOCKS5 與混合代理設定連接埠。實際使用時不必同時開啟三種連接埠，桌面用戶端最常使用的是 mixed-port。

port: 7890
socks-port: 7891
mixed-port: 7892
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "change-this-controller-secret"

三種代理連接埠有什麼差異

同一個 IP 與連接埠不能同時由兩個程式監聽。如果日誌出現 address already in use 或 bind: Only one usage of each socket address，應先檢查連接埠是否被舊的 Clash 程序、其他代理工具或本機開發服務佔用。Windows 可在終端機執行 netstat -ano | findstr :7890，找出對應的 PID。

allow-lan 與 bind-address

allow-lan: false 表示不向區域網路裝置提供代理入口。改為 true 後，手機或其他電腦可以將代理伺服器填寫為目前電腦的區域網路位址，例如 192.168.1.20:7890。此時也要允許 Windows 防火牆放行對應連接埠。

bind-address 決定監聽位址。僅供本機使用時，綁定 127.0.0.1 會更明確；需要區域網路存取時，可依核心支援狀況使用 * 或指定網卡位址。只修改 allow-lan 不代表其他裝置一定能連線，防火牆、訪客網路隔離與路由器 AP 隔離也可能阻擋存取。

mode、log-level 與控制連接埠

DNS 段落：監聽器、解析器與增強模式

DNS 段落決定網域名稱的解析方式。它不僅會影響規則比對，也會影響 TUN 模式下的網域接管。常見的基礎結構如下：

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "+.msftconnecttest.com"
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - tls://1.1.1.1:853
  fallback:
    - https://dns.google/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

enable、listen 與 default-nameserver

enable 控制內建 DNS 模組。listen 是 DNS 服務的監聽位址，範例使用本機 UDP/TCP 連接埠 1053。如果其他本機 DNS 程式已佔用該連接埠，日誌會顯示監聽失敗。

default-nameserver 主要用於解析 DoH、DoT 等上游伺服器本身的網域名稱，也常稱為引導 DNS。為避免循環依賴，這裡通常填寫可直接存取的 IP 位址，而不是另一個必須先解析的網域名稱。

nameserver、fallback 與策略解析

nameserver 是主要解析器，可以是一般 DNS 位址，也可以是 DoH 或 DoT 位址。fallback 與 fallback-filter 是經典 Clash 設定中常見的備援解析結構。mihomo 也支援 nameserver-policy、proxy-server-nameserver、direct-nameserver 等細分欄位，可依網域規則或代理節點的解析用途選擇不同上游。

不要將「寫了多個 DNS」理解成所有請求都會同時採用全部結果。核心會依據欄位語意、過濾條件與回應結果選擇解析路徑。遇到網域可以解析但網站無法開啟時，應同時查看 DNS 日誌、規則命中情況與節點連線，不能只根據瀏覽器錯誤判斷。

fake-ip 與 redir-host

proxies：單一代理節點欄位

proxies 儲存手動定義的節點。訂閱通常會自動產生這一段。不同協定所需欄位各異，但每個節點至少要有唯一名稱、協定類型、伺服器位址與連接埠。

proxies:
  - name: "SS-HK-01"
    type: ss
    server: hk.example.net
    port: 443
    cipher: aes-128-gcm
    password: "example-password"
    udp: true

  - name: "VMess-JP-01"
    type: vmess
    server: jp.example.net
    port: 443
    uuid: 11111111-2222-3333-4444-555555555555
    alterId: 0
    cipher: auto
    tls: true
    servername: jp.example.net
    network: ws
    ws-opts:
      path: /gateway
      headers:
        Host: jp.example.net

通用欄位與協定欄位

節點能出現在清單中，只代表 YAML 已成功解析，不表示連線參數正確。驗證資訊錯誤通常會表現為握手失敗；伺服器位址無法解析會顯示 DNS 錯誤；WebSocket 路徑或 Host 不一致，通常會表現為連線建立後立即中斷。排查時應在用戶端開啟「日誌」，並暫時將等級切換為 debug，再針對單一節點發起延遲測試。

proxy-providers 與 proxy-groups

節點提供器 proxy-providers

proxy-providers 可以從本機檔案或遠端位址載入一組節點。與直接將所有節點寫入 proxies 相比，提供器更適合將節點來源與策略群組結構分開管理。

proxy-providers:
  provider-main:
    type: http
    url: "https://example.com/subscription"
    path: ./providers/provider-main.yaml
    interval: 3600
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

interval: 3600 表示每 3600 秒檢查一次更新；健康檢查的 interval: 600 表示每 10 分鐘執行一次測試。提供器下載失敗時，應檢查訂閱位址是否可存取、系統時間、代理啟動階段是否存在循環依賴，以及儲存路徑是否可寫入。

策略群組的類型與引用

proxy-groups:
  - name: "節點選擇"
    type: select
    proxies:
      - "自動選擇"
      - "故障轉移"
      - DIRECT
    use:
      - provider-main

  - name: "自動選擇"
    type: url-test
    use:
      - provider-main
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80

  - name: "故障轉移"
    type: fallback
    use:
      - provider-main
    url: https://www.gstatic.com/generate_204
    interval: 300

tolerance: 80 表示延遲差距在 80 毫秒以內時，自動選擇群組不必頻繁切換。數值過小可能導致節點因輕微網路波動而反覆變更；數值過大則可能繼續保留明顯變慢的節點。家用寬頻可從 50 至 100 毫秒開始調整。

rules 與 rule-providers：分流的比對順序

rules 決定連線交給哪個策略群組。規則會由上到下比對，命中第一條後就停止繼續檢查，因此越具體的規則通常越靠前，最後再放兜底規則。

rules:
  - DOMAIN,api.example.com,節點選擇
  - DOMAIN-SUFFIX,example.net,節點選擇
  - DOMAIN-KEYWORD,stream,自動選擇
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

常見規則類型

no-resolve 用於避免某些 IP 規則為了比對而額外觸發網域解析。它不是所有規則都需要的通用後綴。若將 MATCH 放在第一行，後續規則永遠沒有機會命中；若規則引用不存在的策略群組，載入時可能直接報錯，也可能在處理連線時顯示找不到策略。

規則提供器 rule-providers

rule-providers:
  private-network:
    type: http
    behavior: ipcidr
    format: yaml
    url: "https://example.com/rules/private-network.yaml"
    path: ./ruleset/private-network.yaml
    interval: 86400

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,節點選擇

behavior 必須與規則集內容相符，常見值包括 domain、ipcidr 與 classical。將網域規則集宣告為 ipcidr，會導致內容無法正確解析。mihomo 的規則集還涉及 format；遠端檔案採用 YAML、文字或二進位格式時，必須填寫對應值。

TUN 段落與透明代理參數

TUN 模式會建立虛擬網路介面，用於接管未單獨設定代理的應用程式流量。它與系統代理不是同一個入口。常見的 mihomo 設定如下：

tun:
  enable: true
  stack: mixed
  dns-hijack:
    - any:53
    - tcp://any:53
  auto-route: true
  auto-detect-interface: true
  strict-route: false

啟用 TUN 後出現「瀏覽器能開、遊戲斷網」或「無法存取區域網路裝置」時，應依序檢查執行權限、路由表、DNS 接管、區域網路網段直連規則與其他 VPN。不要同時開啟多個會建立預設路由的網路工具。Windows 上也可以執行 route print，查看預設路由與介面優先順序。

一份易讀的最小設定與排錯流程

以下結構省略了真實驗證資訊，但保留從入口到規則的完整引用鏈。檢查設定時，可以從最後一行的策略群組反向追蹤：規則引用「節點選擇」，「節點選擇」引用「範例節點」，「範例節點」則包含伺服器參數。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query

proxies:
  - name: "範例節點"
    type: ss
    server: 203.0.113.10
    port: 443
    cipher: aes-128-gcm
    password: "replace-with-valid-password"
    udp: true

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

rules:
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

依錯誤類型逐層檢查

  1. 檔案無法載入：先檢查 Tab、縮排、冒號、引號與重複鍵。此時不要先測試節點，因為核心尚未成功讀取設定。
  2. 設定已載入但策略群組為空：檢查 proxies 是否包含節點、use 的提供器名稱是否正確，以及 provider 檔案是否下載成功。
  3. 節點測試失敗：核對 server、port、驗證欄位、TLS 名稱與傳輸參數，再檢查伺服器網域是否能夠解析。
  4. 只有部分網站無法開啟：查看連線日誌中的規則命中情況、目標網域、策略群組與實際節點，確認規則順序是否將流量提前送往 DIRECT 或 REJECT。
  5. 系統代理有效但其他程式未經代理：確認程式是否遵循系統代理；若不遵循，再評估 TUN，不要透過重複新增寬泛規則來掩蓋入口問題。
  6. 更新訂閱後修改內容消失：將本機 DNS、TUN 或規則調整移至用戶端支援的覆寫或合併設定中。

欄位相容性與維護建議

Clash for Windows 0.20.39 使用的 Clash 核心設定，與持續更新的 mihomo 設定並不完全等價。較新的訂閱可能包含舊核心不認識的協定、規則集格式或 DNS 欄位。遇到 field not found、unsupported proxy type 這類錯誤時，應先確認用戶端實際呼叫的核心及版本，而不是只看介面名稱。

日常維護可以將設定分成三類：訂閱負責節點，規則提供器負責可更新的規則集，本機覆寫負責連接埠、DNS 與 TUN。這樣既能減少手動合併，也能讓問題落在明確區域。每次修改只處理一個主題，例如先修改 DNS 並重新載入，確認解析正常後再啟用 TUN。

設定檔的核心關係並不複雜：入站連接埠接收流量，DNS 提供網域資訊，規則決定策略群組，策略群組選擇節點，節點建立遠端連線。沿著這條鏈檢查，比反覆切換節點或一次替換整份 YAML 更容易找到具體欄位。

查看用戶端下載