CONFIG FILE REFERENCE

Clash 設定欄位

依照 YAML 的依賴關係查閱連接埠、DNS、代理節點、策略組、規則與覆寫。範例採用可直接檢查的結構，實際伺服器參數仍應以訂閱服務提供的設定為準。

YAML 載入順序 通用欄位與 DNS 代理與策略組 規則與覆寫

SECTION SELECTOR

章節目錄

CHAPTER 01 / INPUT

YAML 結構總覽與載入關係

Clash 設定檔是一份 YAML 文件。它不是逐行執行的指令稿，而是一組解析後交由核心處理的鍵值、清單與物件。頂層欄位決定監聽連接埠、運作模式、DNS 行為與控制介面；代理節點放在 proxies，或由 proxy-providers 引入；策略組透過名稱引用節點與其他策略組；規則清單再將網域、IP、程序或網路類型交給指定策略。閱讀設定時，應先確認物件是否存在，再確認引用名稱完全一致，最後檢查規則順序。只盯著某一條規則，很容易忽略它引用的策略組根本沒有載入。

YAML 依靠縮排表達層級。建議統一使用兩個空格，不要使用定位字元。清單項目前以短橫線表示，短橫線後仍應保留一個空格。冒號用於分隔鍵和值，冒號後通常也要有空格。包含冒號、井字號、方括號或特殊布林值的名稱，適合用引號包住。註解從 # 開始，只用於說明，不會傳遞給核心。縮排正確但欄位放錯層級時，解析器可能不會在預期位置讀取該欄位，因此「檔案能開啟」不等於「欄位已生效」。

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

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query

proxies:
  - name: "範例節點"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

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

rules:
  - DOMAIN-SUFFIX,example.org,節點選擇
  - MATCH,DIRECT

上面的最小結構展示了完整引用鏈：rules 中的「節點選擇」必須與 proxy-groups 的名稱完全相同；策略組中的「範例節點」也必須與 proxies 中的節點名稱一致。名稱會區分字元、空格及全形半形符號。複製設定片段時，若只複製規則而漏掉策略組，或只複製策略組而漏掉節點，最後都會形成懸空引用。部分用戶端會在匯入階段提示，另一些用戶端只會在啟動核心時記錄錯誤，因此查看用戶端日誌是必要步驟。

頂層欄位的建議排列

YAML 規範不要求固定的頂層順序，但為了方便維護，建議依「運作入口、DNS、節點來源、節點、策略組、規則來源、規則」排列。這樣的順序接近資料依賴：先決定流量如何進入核心，再決定網域如何解析，接著準備可用出口，最後執行比對。訂閱產生器可能採用不同順序，只要縮排與引用正確，通常不影響結果。手動維護時保持順序穩定，可以減少合併時誤刪，也方便比較更新前後的差異。

層級 常見欄位 檢查重點
運作入口 mixed-port、mode、allow-lan 連接埠衝突、監聽範圍、模式是否符合預期
解析層 dns、hosts 增強模式、上游位址、排除網域
出口層 proxies、proxy-providers 節點名稱、協定參數、來源更新
決策層 proxy-groups、rules 引用關係、比對順序、最終兜底

從訂閱匯入的設定通常會被用戶端儲存為本機副本。直接編輯副本雖然方便測試，但下一次訂閱更新可能會重新產生檔案。需要長期保留的本機規則，應放入用戶端支援的覆寫、合併或腳本入口，而不要依賴修改快取檔案。若目前目標只是完成首次連線，應先依快速入門流程確認訂閱可用，再回到本頁調整結構。如此可分開處理「訂閱本身無法使用」與「自訂欄位寫錯」這兩類問題。

CHAPTER 02 / RUNTIME

通用欄位：連接埠、模式、區域網路與控制介面

通用欄位決定核心如何接收應用程式流量，以及如何提供管理能力。桌面用戶端通常會在圖形介面中管理這些值，但設定檔仍是最終參考。最常見的入口是 mixed-port，它在同一個連接埠接收 HTTP 與 SOCKS5 代理請求，適合系統代理與手動填寫代理位址的應用程式。舊版設定也可能分別使用 port 與 socks-port。若同時定義多個入口，請確認連接埠號沒有重複，也沒有被其他程式佔用。

mixed-port: 7890
redir-port: 7892
tproxy-port: 7893

allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true

redir-port 與 tproxy-port 主要用於透明代理情境，通常由路由規則、閘道腳本或特定用戶端自動接入。一般桌面系統只使用系統代理時，不需要為了欄位齊全而強行啟用。TUN 模式也有自己的流量入口與路由流程，不能只靠增加一個監聽連接埠完成。若要比較系統代理與 TUN 的涵蓋範圍，可閱讀TUN 模式與系統代理的差異，再根據應用程式是否讀取系統代理決定接管方式。

運作模式與規則行為

mode 常見值為 rule、global 與 direct。規則模式依照 rules 由上而下比對，是日常使用的主要方式；全域模式將流量交給全域策略選擇，適合暫時測試節點是否可用；直連模式繞過代理出口，適合排除本地網路問題。切換模式不會改寫規則內容，只會改變決策入口。排錯時可暫時切換至全域模式：若全域模式可以存取，而規則模式失敗，應重點檢查規則命中與策略組；若全域模式也失敗，則應先檢查節點、協定參數及系統接管狀態。

allow-lan 控制區域網路裝置是否可以存取本機監聽連接埠。設為 true 後，還要搭配 bind-address、作業系統防火牆及區域網路位址使用。開放監聽表示同一網路中的裝置可能向該連接埠傳送請求，因此只應在明確需要共用代理時啟用，並為控制介面設定存取限制。僅在本機使用時保留 false 會更容易維護。若用戶端介面提供「允許區域網路連線」開關，應避免同時在多個覆寫層重複設定，以免介面顯示與最終設定不一致。

控制介面與設定儲存

external-controller: 127.0.0.1:9090
secret: "your-dashboard-password"
external-ui: dashboard
profile:
  store-selected: true
  store-fake-ip: true

external-controller 提供控制 API，圖形用戶端與面板可透過它讀取策略組、切換節點或重新載入設定。本機管理時綁定 127.0.0.1 即可。若綁定至所有網路介面，必須同步考慮存取控制、防火牆及實際使用環境。secret 用於控制介面驗證，範例值應替換為本機自訂內容。external-ui 指向面板靜態檔案目錄，它不是網路節點來源，也不會改變代理規則。

profile.store-selected 用於保存策略組選擇，讓核心重新啟動後可以恢復上次的選擇。store-fake-ip 用於保存 Fake-IP 對映，減少重新啟動後對映變化帶來的影響。是否由用戶端接管這些欄位取決於用戶端實作；圖形用戶端可能將狀態寫入自身資料庫，而不是同一份 YAML。遇到「修改後重新啟動又恢復」的情況，應先判斷欄位來自訂閱、覆寫還是用戶端偏好設定，不能只是不斷編輯同一個快取檔案。

連接埠佔用檢查

核心啟動失敗並提示位址已被使用時，先關閉重複啟動的用戶端執行個體，再檢查同一份設定中是否讓多個監聽欄位使用相同連接埠。變更連接埠後，還要同步更新系統代理或應用程式內的手動代理設定。

log-level 常用於控制日誌詳細程度。日常執行可使用 info；排查規則命中、DNS 請求或連線建立過程時，可以暫時提高日誌詳細度，完成後再恢復，避免大量紀錄掩蓋關鍵錯誤。ipv6 決定核心相關功能是否處理 IPv6，但不能單獨保證本地網路具備可用的 IPv6 路由。啟用後若出現連線等待，應分別檢查本地網路、DNS 回應與規則涵蓋範圍，不要把所有問題歸因於單一開關。

CHAPTER 03 / RESOLUTION

DNS 欄位：上游解析、Fake-IP 與回退規則

Clash 的 DNS 模組位於網域請求與規則比對之間。它可以接收本機或 TUN 接管的 DNS 查詢，再依設定選擇上游伺服器。DNS 設定的目標不是單純堆疊位址，而是釐清三個問題：查詢從哪裡進入、使用哪一組上游，以及解析結果如何配合規則。系統代理模式下，部分應用程式仍可能直接使用系統 DNS；TUN 模式搭配 DNS 劫持時，涵蓋範圍通常更完整。若瀏覽器可用而其他應用程式解析失敗，應先確認該應用程式的 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"
    - "*.local"
    - "time.*.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
  proxy-server-nameserver:
    - https://1.1.1.1/dns-query

enable 控制內建 DNS 是否啟用，listen 指定監聽位址。監聽 0.0.0.0 時會涉及區域網路存取範圍，應配合實際網路環境處理；只供本機使用時，可採用本機迴路位址或由用戶端自動設定。default-nameserver 通常使用可直接連線的 IP 位址，用於解析 DoH 上游本身的網域等基礎工作。它不是所有查詢的主要出口。一般網域查詢主要交給 nameserver，代理伺服器網域可由 proxy-server-nameserver 個別解析，避免建立代理連線前出現循環依賴。

Fake-IP 與 Redir-Host 的處理差異

enhanced-mode: fake-ip 會為網域回傳保留位址範圍內的對映位址。應用程式接著連線到該位址時，核心會依對映還原原始網域，再執行網域規則與代理決策。此流程有助於保留網域資訊，也方便 TUN 情境統一處理。fake-ip-range 應使用專用保留網段，不應改成區域網路正在使用的位址範圍。對映位址不是遠端伺服器的真實位址，因此使用封包擷取工具觀察連線時看到保留位址，屬於正常現象。

部分區域網路裝置探索、時間同步、遊戲或依賴回傳真實位址的應用程式不適合 Fake-IP。此時可將相關網域加入 fake-ip-filter，讓它們使用真實解析結果。過濾項目應盡量具體，先從確認異常的網域開始，不要直接加入過寬的頂級比對，否則會削弱網域規則的可見性。關於對映流程與排除情境，可繼續閱讀Clash Fake-IP 模式原理。

redir-host 更接近傳統解析流程，核心取得真實 IP 後再處理連線。它對依賴真實位址的程式較直觀，但網域資訊可能在後續 IP 連線階段遺失，規則比對會更多依賴解析快取或嗅探。兩種模式沒有適用於所有網路的固定答案。一般網頁存取、TUN 全域接管及大量網域規則通常適合先測試 Fake-IP；存在區域網路服務、特殊遊戲或企業內網網域時，應逐項補充過濾，而不是立即改動整個 DNS 架構。

回退、策略與分流解析

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    domain:
      - "+.example.net"
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query
    "geosite:geolocation-!cn":
      - https://1.1.1.1/dns-query

fallback 與 fallback-filter 用於依條件選擇備用結果。設定時需要了解用戶端所使用核心對並行查詢、結果過濾及 Geo 資料的處理方式，不能把「填寫備用位址」理解為所有失敗都會自動依固定順序重試。nameserver-policy 可依網域或規則集合指定解析伺服器，適合內外網路、家庭網域與工作網域需要不同解析路徑的情況。策略鍵引用 geosite 時，本機 Geo 資料必須可讀取，否則對應比對無法按預期運作。

DNS 排錯順序

先確認內建 DNS 已開始監聽，再確認查詢確實進入該連接埠；接著檢查上游網域能否透過基礎 DNS 解析，最後核對 Fake-IP 過濾與規則命中。只更換上游位址，無法修復監聽、劫持或路由層的問題。

常見故障可以依現象分支處理：所有網域失敗但直接存取 IP 正常，重點檢查監聽與上游；只有代理節點網域失敗，檢查 proxy-server-nameserver 與基礎解析；區域網路名稱失敗，檢查搜尋網域、hosts 與 Fake-IP 排除；規則命中與預期不同，檢查是否保留網域資訊以及 Geo 資料是否已載入。修改後應重新載入設定並查看日誌，不要同時改動增強模式、上游位址與 TUN 劫持三個層面，否則難以判斷哪一項真正生效。

CHAPTER 04 / ENDPOINTS

代理節點欄位：名稱、協定參數與傳輸層

proxies 是代理節點物件清單。每個物件至少需要名稱、協定類型、伺服器位址、連接埠，以及對應協定的驗證參數。節點名稱不僅用於顯示，也會被策略組引用，因此必須保持唯一。伺服器可以是網域或 IP；使用網域時，建立連線前需要完成 DNS 解析。連接埠必須是伺服器實際監聽的連接埠，不能與本機代理入口連接埠混淆。訂閱產生的節點參數通常已成套提供，手動修改其中一個欄位可能破壞伺服器與用戶端的協商。

proxies:
  - name: "SS 範例"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "Trojan 範例"
    type: trojan
    server: proxy.example.com
    port: 443
    password: "your-password"
    sni: proxy.example.com
    skip-cert-verify: false
    udp: true

Shadowsocks 節點使用 cipher 與 password。加密方式必須與伺服器一致，欄位拼寫及大小寫也要符合核心支援範圍。Trojan 節點通常透過 TLS 建立連線，sni 用於指定握手中的伺服器名稱。skip-cert-verify 設為 false 時會執行憑證驗證，正常的公開憑證情境應保留驗證。若憑證名稱與連線網域不一致，應先核對伺服器設定與訂閱內容，而不是將關閉驗證當作長期修復方式。

VMess、WebSocket 與 TLS

proxies:
  - name: "VMess WS 範例"
    type: vmess
    server: proxy.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    servername: proxy.example.com
    network: ws
    ws-opts:
      path: /service
      headers:
        Host: proxy.example.com

VMess 的 uuid、alterId、傳輸網路與 TLS 參數必須與伺服器匹配。WebSocket 設定放在 ws-opts 下，路徑與 Host 標頭屬於傳輸層協商內容。欄位若縮排到節點物件外，YAML 仍可能解析，但核心不會將它視為該節點的 WebSocket 參數。使用 gRPC、HTTP 或其他傳輸時，應改用對應選項，不能保留無關的 ws-opts 並期待自動轉換。

TLS 相關欄位在不同協定物件中可能使用 sni 或 servername。複製片段前應對照目前核心支援的欄位，不要只因欄位名稱相近就進行替換。伺服器位址、TLS 伺服器名稱與 HTTP Host 可以相同，也可能各自承擔不同作用：伺服器位址決定連線目標；SNI 參與 TLS 握手；Host 標頭由應用層傳輸使用。排查握手失敗時，應分別檢查這三個層面，而不是只測試網域能否解析。

UDP、介面與鏈式出口

udp: true 表示節點允許處理 UDP，但最終是否可用仍取決於協定、伺服器及本機接管方式。應用程式發出 UDP 請求不代表系統代理會自動接管；許多系統代理設定主要涵蓋 TCP。TUN 或透明代理情境較容易統一處理 UDP，但也需要正確的路由與 DNS 設定。遊戲、語音或 QUIC 連線異常時，應先確認流量是否進入核心，再判斷節點是否支援，不能僅憑節點物件中的布林值下結論。

interface-name、routing-mark 等欄位用於限制出口介面或配合系統路由，主要出現在多網卡、伺服器及路由器環境。設定錯誤可能讓代理連線再次進入代理入口，形成循環。鏈式代理可透過 dialer-proxy 等機制指定撥號出口，但被引用的節點或策略組必須先存在，而且要避免互相引用。一般用戶端設定沒有明確鏈路需求時，不建議增加這些欄位。

欄位組別 決定內容 常見錯誤
基礎連線 server、port、type 位址無法解析、連接埠與伺服器不一致
驗證參數 password、uuid、cipher 複製不完整、混用協定欄位
TLS 層 sni、servername、憑證驗證 名稱不匹配、用關閉驗證掩蓋設定問題
傳輸層 network、ws-opts 等 路徑錯誤、選項縮排到錯誤層級

匯入訂閱後，不應靠猜測修改協定參數。先執行用戶端提供的設定更新，再檢查節點名稱是否已進入策略組。節點清單為空時，問題通常發生在訂閱擷取、格式轉換或提供者載入階段；節點存在但連線失敗時，再檢查協定參數、DNS 與系統時間。用戶端下載與平台差異可在用戶端下載頁核對，停止更新的用戶端遷移可參考設定轉移步驟。

CHAPTER 05 / POLICY

策略組欄位：手動選擇、自動測試與故障轉移

proxy-groups 將節點、內建出口及其他策略組組織成可供規則引用的決策物件。規則通常不直接寫入某個節點名稱，而是寫入策略組名稱，這樣訂閱更新或節點變更時就不必重寫所有規則。常見內建出口包括 DIRECT 與 REJECT。前者直接連線至目標，後者終止符合條件的流量。策略組名稱同樣需要唯一；若名稱與節點重複，閱讀及維護都會變得困難，建議使用「節點選擇」「自動選擇」「故障轉移」等能表達用途的名稱。

proxy-groups:
  - name: "節點選擇"
    type: select
    proxies:
      - "自動選擇"
      - "故障轉移"
      - "SS 範例"
      - DIRECT

  - name: "自動選擇"
    type: url-test
    proxies:
      - "SS 範例"
      - "Trojan 範例"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: "故障轉移"
    type: fallback
    proxies:
      - "SS 範例"
      - "Trojan 範例"
    url: https://www.gstatic.com/generate_204
    interval: 300

Select、URL-Test 與 Fallback

select 用於手動選擇。它適合作為頂層入口，讓使用者在自動組、故障組、單一節點與直連之間明確切換。url-test 會依測試位址檢查候選項目，並根據測試結果進行選擇。測試結果只反映連往指定 URL 的連線表現，不等同於所有網站、所有協定及所有時段的體驗。tolerance 用於減少候選項目結果接近時頻繁切換，數值單位及具體處理方式由核心實作決定。

fallback 依清單順序選擇可用項目，當前項目無法使用時才切換至後續項目，適合出口優先順序明確的情境。load-balance 用於將連線分配至多個候選項目，但需要考慮工作階段一致性：登入、付款或依賴固定出口的服務，可能不適合在不同連線間切換出口。自動測試與負載分配都不是「節點越多越好」，候選項目過多會增加檢測請求及維護成本。應先依地區、用途或協定篩選，再建立規模可控的策略組。

使用代理提供者填入策略組

proxy-providers:
  airport:
    type: http
    url: "https://example.com/api/v1/client/subscribe?token=xxxx"
    path: ./providers/airport.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "提供者節點"
    type: select
    use:
      - airport

proxy-providers 將遠端節點集合儲存為本機提供者檔案。type: http 表示透過位址更新，path 指定本機快取位置，interval 指定週期更新間隔。範例訂閱位址使用明顯的測試值，實際位址應從訂閱服務複製，並避免在公開文件或截圖中暴露。health-check 用於提供者層級的可用性檢查，它可以與策略組自己的測試機制同時存在，但兩者間隔過短會造成重複檢測。

策略組透過 use 引用提供者，透過 proxies 引用靜態節點或其他組別。兩種來源可以依核心支援方式組合，但維護時應明確節點來自何處。訂閱更新後節點名稱變更時，直接寫在 proxies 中的舊名稱可能失效；使用提供者引用則更適合動態集合。需要進一步篩選時，可在支援的核心中使用 filter 或排除運算式，依節點名稱建立地區組。運算式應先用少量名稱測試，避免因命名規則變更而得到空組。

策略組的依賴方向

策略組可以引用其他策略組，但依賴必須保持單向。例如「節點選擇」引用「自動選擇」是合理結構；如果「自動選擇」又回頭引用「節點選擇」，就會形成循環。設計策略層時，可以由下而上排列：底層是靜態節點與提供者，中層是地區篩選與自動測試，頂層是供規則引用的用途組。媒體、工作、下載等用途組再引用頂層出口，不要讓底層測速組引用業務組。

策略組為空時

先檢查 use 中的提供者名稱，再檢查提供者檔案是否成功更新；使用名稱篩選時，暫時移除篩選運算式，確認原始節點是否存在。空組通常不是規則問題，規則只會將請求送到已定義的策略組。

interval 是以秒為單位的週期設定時，應依實際需要設定，不必追求高頻率。節點訂閱更新、健康檢查與策略測試是三種不同操作：訂閱更新會改變候選集合；健康檢查判斷節點是否可連線；策略測試則在候選項目之間進行選擇。排錯時分別手動觸發，並觀察哪個步驟失敗。若用戶端介面同時提供自動更新週期，應確認它更新的是整份設定還是提供者，避免多個計時器重複請求。

CHAPTER 06 / MATCHING

規則語法、比對順序與規則集

rules 是有順序的清單。連線會從第一條開始逐條向下檢查，命中後立即使用該條指定的策略，後續規則不再處理同一連線。因此規則的關鍵不只在內容，也在位置。具體網域、程序或網段通常放在前面，範圍較大的 Geo 規則放在後面，最後使用 MATCH 兜底。過早放置寬泛規則，會讓下面的精確規則永遠沒有機會命中。

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

DOMAIN 精確比對完整網域；DOMAIN-SUFFIX 比對指定網域及其子網域；DOMAIN-KEYWORD 依關鍵字比對，範圍更廣，容易誤傷包含相同字串的其他網域。能使用精確網域或後綴時，不應優先使用關鍵字。網域規則依賴連線過程中可取得的網域資訊。若應用程式直接連線 IP，或 DNS 處理沒有保留網域，匹配可能轉向 IP 類規則。

IP、連接埠、程序與網路類型

IP-CIDR 用於 IPv4 網段，IPv6 則使用相應的 IPv6 規則類型。區域網路保留位址通常應在 GeoIP 之前直連。no-resolve 表示比對該 IP 規則時，不為取得 IP 而主動觸發網域解析，可用於避免額外查詢及規則階段循環，但是否適合仍要視規則類型與實際流量而定。使用 CIDR 時應確認前綴長度，過寬的網段可能涵蓋非預期位址。

rules:
  - PROCESS-NAME,example-app.exe,DIRECT
  - DST-PORT,22,節點選擇
  - NETWORK,udp,自動選擇
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,節點選擇

程序規則依賴作業系統權限及用戶端核心能力，不同平台取得程序名稱的方式並不完全一致。Windows 常見的是可執行檔名稱，macOS 與 Linux 可能依程序名稱或路徑提供資訊；行動平台通常無法以桌面平台的方式識別所有應用程式。連接埠規則只反映目標連接埠，不能證明流量用途。許多服務共用連接埠，僅憑連接埠分流可能涵蓋過廣。NETWORK 可區分 TCP 與 UDP，但更適合作為特定需求的補充，不應取代網域與 IP 規則。

Rule Provider 與行為類型

rule-providers:
  direct-domains:
    type: http
    behavior: domain
    format: yaml
    path: ./ruleset/direct-domains.yaml
    url: https://example.com/rules/direct-domains.yaml
    interval: 86400

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

rules:
  - RULE-SET,direct-domains,DIRECT
  - RULE-SET,private-networks,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

rule-providers 將大量規則拆分至獨立檔案。behavior: domain 表示內容依網域類載荷解讀，ipcidr 用於網段，部分核心還支援更通用的規則集合行為。行為類型必須與遠端檔案內容一致。網域清單不能標記為 IP 網段行為，經典規則文字也不能直接當作純網域載荷。format 則描述檔案格式，更新失敗時要同時檢查網路存取、檔案格式、儲存路徑與解析日誌。

規則集更新週期與訂閱更新彼此獨立。節點訂閱更新不會自動保證外部規則集已重新整理，規則集重新整理也不會改變節點。GeoIP、GeoSite 與外部規則集屬於不同資料來源。遇到地區規則過舊時，應確認用戶端使用的資料檔案位置與更新功能，避免只更新訂閱。關於 Geo 資料載入問題，可以前往說明中心繼續依錯誤現象查找。

建立可解釋的規則順序

建議依「本機與區域網路、人工精確規則、業務規則集、地區規則、最終兜底」排列。每個區段前可以寫註解，說明規則來源與用途。人工規則數量少時直接寫入主設定，方便檢查；數量多且需要獨立更新時，再使用規則提供者。不要將多個來源的規則機械式拼接後直接投入使用，應檢查是否存在重複項目、相反策略及過寬關鍵字。

規則未生效

先從連線日誌確認實際命中的規則，再向上查找是否有更早的寬泛規則攔截。若日誌只顯示 IP，檢查 DNS 模式、嗅探與應用程式連線方式；若策略名稱不存在，則回到策略組引用關係處理。

測試規則時一次只修改一個區段。可以先加入一條精確網域規則並置於清單前部，重新載入後存取對應網域，透過日誌確認命中。確認語法與策略組有效後，再逐步擴大到後綴或規則集。直接切換全域模式只能驗證節點鏈路，不能證明規則正確。完成測試後應恢復規則模式，並檢查最終 MATCH 指向是否符合預期。

CHAPTER 07 / MAINTENANCE

覆寫、合併、自動更新與設定排錯

訂閱設定會隨遠端內容更新，本機修改應放在穩定的自訂層。常見用戶端提供覆寫、合併、擴充腳本或設定片段功能，但不同用戶端對陣列與物件的處理方式可能不同。物件欄位通常可以依鍵覆寫，例如將 mode 改為 rule，或為 dns 補充子欄位；陣列欄位則可能整體取代、追加到前後，或依用戶端定義的語法處理。rules、proxies 與 proxy-groups 都是陣列，錯誤地整體覆蓋會使訂閱原有內容消失。

設定維護應先區分四個來源：遠端訂閱原文、用戶端產生的執行設定、本機覆寫片段，以及用戶端自身偏好。介面中看到的最終狀態可能是四者的合併結果。排查時應找到用戶端提供的「查看執行設定」或日誌輸出，而不要只開啟下載下來的訂閱檔案。若更新訂閱後自訂規則消失，表示修改落在遠端副本或快取層；若介面改動後 YAML 沒有變化，表示該項目可能儲存在用戶端設定中。

物件覆寫與陣列追加

# 通用覆寫示意，實際入口以用戶端支援方式為準
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - "*.lan"
    - "*.local"

上面的物件結構適合表達最終目標，但不能說明某個用戶端如何合併陣列。例如 fake-ip-filter 若採用取代語意，寫入兩項後會覆蓋訂閱原本的清單；若採用追加語意，則會保留原清單並增加兩項。使用前應在用戶端文件或執行設定中確認。規則陣列尤其要注意插入位置：需要優先比對的本機規則必須放在遠端規則之前；只追加到 MATCH 之後不會生效，因為流量已在兜底規則處結束。

策略組也有同樣問題。若要為「節點選擇」增加一個本機組，不應複製整份遠端策略組清單長期維護，因為訂閱更新後新增的組別不會自動進入副本。較穩妥的方式是使用用戶端提供的組別覆寫、腳本處理或提供者引用，在最終設定中只變更目標組。用戶端不支援細緻合併時，可以縮小自訂範圍，或將長期規則放到獨立規則提供者中。

自動更新的三個層次

自動更新至少包括整份訂閱、代理提供者及規則提供者三個層次。整份訂閱更新通常由用戶端排程，更新後重新產生完整設定；proxy-providers.interval 更新節點集合；rule-providers.interval 更新規則集合。三者不應混為同一個開關。訂閱位址變更時，只重新整理規則提供者不會取得新節點；規則集過舊時，只重新整理節點訂閱也不會改變規則資料。

設定週期時要考慮內容變化頻率與用戶端運作方式。桌面用戶端長時間關閉時，計時器無法在背景執行，重新啟動後應手動檢查更新時間。更新成功也不等於執行設定已重新載入，部分用戶端會自動套用，部分則需要手動切換或重新載入。可靠的操作順序是：執行更新、確認來源狀態、重新載入最終設定、查看策略組是否保留選擇，再進行存取測試。

建議保留的檢查基線

保留一份能正常啟動的最小設定。每次只增加一個功能區塊，重新載入後檢查日誌。出現問題時回復到上一個可用狀態，比同時修改 DNS、TUN、策略組與規則更容易定位。

從解析錯誤到連線錯誤的排查鏈

第一層是 YAML 解析。常見提示包括縮排錯誤、冒號後缺少空格、引號未閉合、清單層級錯誤及重複鍵。處理時查看錯誤行上下數行，因為真正的結構錯誤可能發生在提示行之前。包含特殊字元的值可以先加上引號；從網頁複製的彎引號與全形標點應改為普通 YAML 字元。解析通過後，再進入欄位驗證，檢查類型是否正確，例如連接埠應為數字，布林值應為 true 或 false。

第二層是引用驗證。逐項確認規則目標存在於策略組或內建出口中，策略組成員存在於節點、提供者或其他組別中，規則提供者名稱與 RULE-SET 引用一致。名稱中的空格最難察覺，可暫時複製名稱進行搜尋。第三層是資源載入，檢查訂閱、代理提供者、規則提供者及 Geo 資料是否可讀取。網路更新失敗時，保留的舊快取可能讓核心繼續啟動，因此要同時查看更新時間與日誌。

第四層是建立連線。節點逾時先檢查伺服器解析、目標連接埠、本地網路與協定參數；TLS 握手失敗則檢查系統時間、伺服器名稱與憑證；只有 UDP 異常時檢查接管方式與節點能力；只有特定網域異常時回到 DNS 與規則命中。第五層是系統流量入口：瀏覽器設定、系統代理、TUN 路由及應用程式自身代理必須與目前方案一致。設定檔完全正確，但系統流量沒有進入核心時，存取結果仍不會改變。

現象 優先檢查 下一步
設定無法載入 縮排、引號、欄位類型、重複鍵 縮減至最小設定後逐段恢復
策略組為空 節點來源、use、篩選運算式 檢查提供者日誌與快取檔案
規則模式異常 實際命中項目、規則順序、策略名稱 使用精確網域規則進行單項測試
網域失敗但 IP 可用 DNS 監聽、上游解析、Fake-IP 確認查詢是否進入核心
更新後自訂內容消失 修改位置、陣列合併語意 移至用戶端覆寫或規則提供者

完成修改後，應保留一條可重複的驗證流程：重新載入設定，確認核心啟動；更新提供者，確認節點與規則集可讀取；檢查策略組選擇；存取一個應直連的網域與一個應走代理的網域；最後查看日誌中的命中結果。若問題仍無法歸類，可前往說明中心依安裝設定、使用技巧與故障排查分類繼續檢查。需要重新理解整份 YAML 的載入順序，可閱讀設定檔 YAML 結構解析；需要重新完成基礎匯入，則返回入門指南，不要在尚未確認訂閱可用時疊加更多覆寫。