YAML 參考 預計閱讀 14 分鐘

Clash YAML 設定檔結構解析：從基礎欄位到規則段落的完整順序

依實際載入順序拆解連接埠、DNS、代理節點、策略組與規則欄位，並說明縮排、引用及欄位覆寫關係。

先讀懂結構：YAML 順序與設定依賴不是同一回事

Clash、Clash Meta 及其後續的 mihomo 核心通常使用 YAML 檔案描述執行參數。完整設定可能同時包含監聽連接埠、執行模式、DNS、代理節點、策略組、規則集與流量嗅探等內容。YAML 對映本身不會透過書寫先後表示業務優先級，因此將 rules 寫在檔案前段，不會讓規則比連接埠欄位更早生效。

實際排查時仍建議依依賴關係閱讀：先確認基礎監聽與執行模式，再確認 DNS，接著檢查節點來源與策略組引用，最後確認規則如何將請求導向策略組。這不是 YAML 解析器強制採用的載入順序，而是一條更容易定位錯誤的檢查路徑。

  1. 基礎欄位決定用戶端如何監聽本機流量，以及採用規則、全域或直連模式。
  2. DNS 欄位決定網域查詢入口、上游伺服器與 Fake-IP 對映方式。
  3. proxies 與 proxy-providers 提供可用的代理節點。
  4. proxy-groups 將節點或其他策略組組織成可選擇的出口。
  5. rule-providers 提供遠端規則集合，rules 決定最終比對順序。

基礎欄位：連接埠、區域網路存取與執行模式

基礎段落通常放在檔案頂端，方便快速確認用戶端開放了哪些入口。不同用戶端可能透過圖形介面覆寫其中部分內容，因此檔案中的值不一定等於執行時的最終值。排查問題時，應同時查看設定檔與用戶端目前的狀態頁面。

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090

mixed-port 同時接收 HTTP 與 SOCKS 代理連線，適合只設定一個本機代理連接埠的情境。部分設定也會分別使用 port 與 socks-port。同一種入口不必重複開放多個互相衝突的連接埠；若連接埠已被其他程式佔用，核心可能無法啟動監聽。

allow-lan 控制區域網路裝置是否能連線至本機代理連接埠。設為 true 時，還要檢查系統防火牆與監聽位址。bind-address 決定監聽的網路介面範圍，但實際可用行為仍應以核心版本為準。僅供本機使用時，關閉區域網路存取更容易控管入口。

mode 常見值包括 rule、global 與 direct。規則模式會逐條比對 rules；全域模式會將流量交由全域策略選擇；直連模式則繞過代理。圖形用戶端中的模式切換經常會直接變更執行時設定，不一定會回寫訂閱檔案。

欄位 主要用途 檢查重點
mixed-port 接收 HTTP 與 SOCKS 代理連線 確認連接埠是否被佔用，以及應用程式是否指向同一連接埠
allow-lan 允許或阻止區域網路裝置連入 監聽位址、防火牆與裝置所在的網段
mode 選擇規則、全域或直連模式 確認用戶端執行狀態是否覆寫檔案中的值
log-level 設定日誌詳細程度 排錯時能否看到 DNS、規則與連線資訊

DNS 段落：查詢入口、上游與 Fake-IP 對映

DNS 設定不只是簡單的伺服器位址清單。啟用內建 DNS 後，核心需要確定監聽入口、解析模式、預設解析伺服器與實際上游。使用 TUN 接管時，DNS 劫持與路由設定也會影響請求是否進入核心。

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://1.1.1.1/dns-query

default-nameserver 主要用來解析加密 DNS 上游本身的網域，通常填寫可直接連線的 IP 位址。nameserver 則負責一般網域查詢。部分 mihomo 設定還會使用 proxy-server-nameserver 專門解析代理伺服器網域，或透過 nameserver-policy 為指定網域選擇不同的上游。

enhanced-mode: fake-ip 會先為網域配置虛擬位址，待連線建立時還原網域資訊並執行規則比對。這能減少應用程式自行解析造成的比對偏差。區域網路主機名稱、某些裝置探索協定、特定遊戲，或依賴真實位址回傳結果的網域，可能需要加入 fake-ip-filter。過濾規則應針對實際異常新增，不宜將大範圍網域全部排除。

代理節點與策略組：先定義成員，再建立出口

proxies 儲存直接寫入檔案的節點。每個節點至少包含名稱、協定類型、伺服器位址、連接埠，以及該協定要求的驗證參數。不同協定的欄位差異很大，不能將一種協定的參數直接複製到另一種協定。訂閱轉換工具產生的節點，也應以核心實際支援的欄位為準。

proxies:
  - name: "節點 A"
    type: socks5
    server: proxy.example.com
    port: 1080
    username: account
    password: passphrase
    udp: true

proxy-groups:
  - name: "節點選擇"
    type: select
    proxies:
      - "自動測速"
      - "節點 A"
      - DIRECT

  - name: "自動測速"
    type: url-test
    proxies:
      - "節點 A"
    url: https://www.gstatic.com/generate_204
    interval: 300

名稱就是引用鍵。策略組中的 節點 A 必須與節點名稱逐字一致，包括空格、大小寫與全形符號。策略組也可以引用另一個策略組，因此可以先建立「自動測速」，再將它作為「節點選擇」的成員。若引用形成循環，核心將無法取得有效出口，應調整層級。

select 由使用者手動選擇成員；url-test 依測試結果自動選擇延遲較低的可用節點；fallback 著重依順序選擇可用成員；load-balance 則依策略在多個成員之間分配連線。延遲測試位址只用於測試可用性與回應時間，不代表所有目標網站的實際速度。

DIRECT、REJECT 等是內建動作，不需要在 proxies 中重複宣告。DIRECT 表示直連，REJECT 表示拒絕連線。規則目標也可以直接指向這些動作，但將常用出口統一指向策略組，通常更方便在用戶端中切換。

規則段落：由上至下比對，第一個命中結果生效

不同於 YAML 頂層對映，rules 是有順序的清單。核心通常從第一條開始檢查，命中後便停止繼續比對。因此具體規則應放在寬泛規則之前，兜底規則則放在最後。若將 MATCH 提前，後續的網域與 IP 規則就會失去作用。

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

DOMAIN 比對完整網域；DOMAIN-SUFFIX 比對指定網域及其子網域；DOMAIN-KEYWORD 依關鍵字比對，範圍通常更廣。IP-CIDR 會套用至目標 IP 網段，加入 no-resolve 可避免為了比對該規則而額外觸發網域解析，但只有在連線內容已包含目標 IP 時才能直接判斷。

GEOIP 依賴地理資料庫將 IP 分類。mihomo 也支援 GeoSite、規則集合與更多規則類型，但能否使用取決於核心版本、資料庫檔案與設定方式。規則目標必須是已存在的策略組、節點名稱或內建動作。若日誌提示找不到策略，應優先檢查規則末端與 proxy-groups 名稱。

規則模式只負責選擇出口，不會自動將所有裝置流量送入 Clash。瀏覽器或系統必須先使用系統代理，或由 TUN 虛擬網路介面接管流量。遇到「規則沒有生效」時，應先確認連線是否出現在用戶端日誌中；若日誌完全沒有該連線，通常應檢查流量入口，而不是繼續修改規則順序。

遠端集合：proxy-providers 與 rule-providers

節點數量較多時，可以使用 proxy-providers 從遠端位址或本機檔案載入節點集合，再由策略組透過 use 引用。規則集合則由 rule-providers 定義，並在 rules 中透過 RULE-SET 呼叫。兩者名稱相近，但提供的資料類型不同，不能互換。

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

proxy-groups:
  - name: "訂閱節點"
    type: select
    use:
      - provider-main

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

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,訂閱節點

path 是遠端內容下載後的本機儲存位置。執行環境必須允許核心寫入相應目錄。interval 通常以秒為單位，表示更新間隔；健康檢查間隔與訂閱更新間隔是兩項獨立設定。健康檢查只會測試現有節點，不會取代訂閱更新。

規則提供器的 behavior 必須與內容結構相符，例如網域集合、IP 網段集合或經典規則格式。不同 mihomo 版本對 format、二進位規則集與行為類型的支援可能不同。載入遠端規則失敗時，應查看日誌中的下載狀態、檔案格式與解析錯誤，不要只確認 URL 能否在瀏覽器中開啟。

縮排、引號與 YAML 類型：最常見的解析邊界

YAML 使用縮排表示層級，建議統一使用空格，不要混用定位字元。同一層級的欄位應保持相同縮排，清單項目使用連字號。下面兩段看似相近，但第二段將 enable 放到了 dns 外部，意義已經改變。

dns:
  enable: true
  enhanced-mode: fake-ip

dns:
enable: true
enhanced-mode: fake-ip

包含冒號、井號、前後空格，或容易被識別為布林值的文字，適合使用引號。節點名稱與策略組名稱只要保持一致，就可以使用中文。連接埠應寫成數字，開關應寫成 true 或 false，不要將所有值都包成字串。某些欄位允許字串形式，但類型是否相容應以核心文件與錯誤日誌為準。

YAML 錨點與引用可以減少重複設定，但複雜訂閱經過用戶端覆寫、格式轉換或重新匯出後，錨點結構可能會被展開。手動維護檔案時可以謹慎使用；若需要頻繁經過訂閱轉換流程，明確寫出關鍵欄位更容易排查。

欄位覆寫關係與完整檢查流程

執行時設定可能來自多個層級：遠端訂閱原文、用戶端本機覆寫、使用者在介面中的暫時選擇，以及核心啟動參數。最終生效值取決於用戶端如何合併這些來源。同一欄位被重複定義時，不應只依檔案位置猜測結果，應查看用戶端產生的最終設定或執行狀態。

策略組目前的選擇通常儲存在用戶端或核心快取中。訂閱更新後，只要組名與成員關係仍然有效，原本的選擇可能會繼續保留；若節點改名或遭刪除，用戶端可能退回組內其他成員。規則更新不代表節點一定可用，節點健康檢查通過也不代表規則目標正確。

  1. 驗證 YAML 語法：確認縮排、冒號、清單符號與引號完整，先排除無法解析的問題。
  2. 檢查本機入口：確認 mixed-port、系統代理或 TUN 狀態，觀察目標連線是否進入日誌。
  3. 檢查 DNS 鏈路：確認查詢已由核心接收、上游可連線，且 Fake-IP 排除範圍合理。
  4. 檢查節點來源：確認靜態節點或代理提供器載入成功，且伺服器網域可以解析。
  5. 檢查名稱引用：從規則目標追查至策略組，再從策略組追查至節點或提供器。
  6. 檢查規則順序：將具體規則放在前面，寬泛規則放在後面，末尾保留明確的兜底規則。
  7. 檢查執行時覆寫：確認用戶端介面中的模式、連接埠與策略選擇沒有覆寫預期設定。

一份能載入、能接管、能解析並能選擇路由的設定，才算形成完整鏈路。遇到故障時，依「入口 → DNS → 節點 → 策略組 → 規則 → 出口」逐段確認，比一次修改多個欄位更容易定位原因。每次只調整一個環節，並結合日誌驗證結果，可以避免語法、網路與規則問題互相干擾。

下載Clash