Clash 設定檔完整參考

01 / DOCUMENT SHAPE

YAML 結構總覽：先看層級，再修改欄位

頂層區塊如何協同運作

一份可執行的 Clash Meta 設定並不是彼此無關的欄位集合，而是一條具有明確引用方向的處理鏈。通用欄位決定監聽連接埠、執行模式與區域網路存取範圍；dns 決定網域如何解析；proxies 與 proxy-providers 提供可用代理；proxy-groups 將代理與其他策略組組織成選擇、測速或故障轉移關係；rule-providers 提供外部規則集合；最後的 rules 依照書寫順序將連線交給某個策略組。只要其中一層名稱對不上，後續結構即使語法正確，也可能在載入或執行階段失效。

YAML 透過縮排表達父子關係，通常使用兩個空格，不應混用定位字元。冒號後需要空格，清單項目以連字號開頭，同層欄位必須維持相同縮排。字串是否加引號取決於內容：一般英文名稱可以直接撰寫；包含冒號、井字號、大括號，或容易被解析為布林值的內容，使用引號較穩妥。策略組名稱含有空格與中文是允許的，但所有引用處都必須逐字一致，包括大小寫、空格與標點。

mixed-port: 7890
mode: rule
log-level: info
allow-lan: 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: socks5
    server: 127.0.0.1
    port: 1080

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

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

映射、序列與純量的差異

dns: 後面接的是映射，也就是一組鍵值欄位；nameserver: 後面是序列，每個上游伺服器各佔一個清單項目；mode: rule 中的 rule 則是純量。最常見的結構錯誤，是把原本應屬於某個清單項目的欄位退回頂層，或讓第二個節點的欄位仍縮排在第一個節點內。複雜節點建議採用「一個連字號開始一個完整物件」的排版，每個物件內的欄位垂直對齊，修改時更容易發現層級錯誤。

YAML 錨點與別名可以重複利用片段，但訂閱轉換、用戶端覆寫與部分編輯器對進階 YAML 語法的處理並不完全一致。面向長期維護的設定，優先使用清楚的明確欄位；只有在大量節點確實共用同一組參數，且已確認載入鏈支援錨點時，才引入 &name 與 *name。重複幾行設定通常比隱藏的繼承關係更容易排查。

最小設定與完整設定

最小設定可以只有監聽連接埠、一個代理、一組策略與結尾規則，但實際使用通常還要加入 DNS、訂閱提供器、規則集合、TUN 與持久化設定。建議先讓最小骨架成功載入，再逐一增加區塊。一次加入整份複雜設定後才開始排錯，很難判斷故障來自 DNS、節點參數還是規則引用。新增區塊時，分別以「載入成功、連線成功、規則正確命中」三個階段驗證，避免把所有異常都歸咎於設定檔無法使用。

設定檔中的註解以 # 開始，適合記錄欄位用途與變更原因，但不要讓關鍵名稱依賴註解說明，並頻繁改寫。訂閱更新可能重建節點區與策略組區，本地註解也可能被覆蓋。長期說明應保存在獨立文件，設定內只留下能協助現場排錯的短註解，例如某條直連規則用於區域網路裝置，或某個 DNS 上游只能透過代理存取。

02 / GENERAL

通用欄位：連接埠、模式、監聽與執行狀態

如何選擇連接埠欄位

port 提供 HTTP 代理連接埠，socks-port 提供 SOCKS5 連接埠，mixed-port 則讓同一個連接埠同時接收 HTTP 與 SOCKS5 請求。桌面用戶端只需要向其他程式提供一個代理位址時，使用 mixed-port 最直接；某些軟體明確要求特定協定，或需要分別記錄兩類連線時，可以拆成獨立連接埠。只要連接埠號未被其他程序佔用即可，不要求固定為某個常見數值。

redir-port、tproxy-port 屬於透明代理入口，通常搭配 Linux 防火牆規則使用，不等同於系統代理連接埠。只撰寫這兩個欄位不會自動接管流量，還需要路由表、策略路由及 nftables 或 iptables 規則協同。圖形化用戶端的 TUN 模式通常由用戶端負責建立虛擬網卡與路由，不應同時照搬路由器上的透明代理規則，否則可能形成重複轉發或迴圈。

mode 決定是否參與規則處理

mode: rule 依照 rules 由上至下匹配，是日常分流的主要模式。global 會讓連線統一進入全域策略，適合暫時確認某個節點是否可用，但會繞過原有規則邏輯；direct 則讓連線直接存取目標，適合判斷故障是否由代理鏈造成。排查「規則未命中」時，第一步就是確認目前執行模式仍為 rule，因為圖形化用戶端的模式切換可能覆蓋設定檔中的初始值。

log-level 控制日誌詳細程度。正常執行可使用 info，定位規則與連線問題時暫時提高至 debug，完成排查後再調回，避免日誌量持續增加。日誌中的規則命中、DNS 查詢、撥號失敗與逾時資訊需要分開查看：命中某個策略組只代表分流結果已確定，不能證明組內最終節點連線成功。

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true
find-process-mode: strict

區域網路存取與監聽範圍

allow-lan 決定其他裝置能否存取 Clash 的監聽連接埠。設為 true 後，還要確認作業系統防火牆已放行對應連接埠，並使用執行 Clash 裝置的區域網路位址作為代理伺服器。bind-address 用於限制監聽位址；僅供本機使用時維持迴路位址範圍，供區域網路共享時才擴大監聽範圍。共享代理不應直接暴露於公網介面，尤其是在雲端伺服器或具有公網位址的網卡環境中。

external-controller 提供控制介面，圖形化用戶端與 Web 面板會透過它讀取連線、日誌與策略狀態。控制介面與代理連接埠用途不同，不能將它當作瀏覽器代理位址。若控制介面允許非本機存取，應設定存取憑證並限制防火牆來源。設定中的控制憑證屬於本機敏感資訊，不應提交至公開儲存庫或發布到公開問題區。

ipv6 影響核心是否處理並回傳 IPv6 位址，但它不是單純的網路加速開關。上游網路、代理節點與目標網站任一環節的 IPv6 路徑不完整，都可能表現為部分連線等待後回退。沒有可用 IPv6 網路時關閉較容易維持行為一致；確實具備完整雙堆疊環境時再啟用，並分別檢查 DNS 回傳與實際連線路徑。

03 / DNS PIPELINE

DNS 設定：解析路徑、Fake-IP 與分流關係

DNS 區塊處理的不只是單一解析問題

Clash 的 DNS 模組既負責將網域解析為位址，也為網域規則、Fake-IP 映射與依策略選擇上游提供基礎。關閉內建 DNS 後，應用程式通常會直接使用系統解析結果，核心可能只能看到目標 IP，導致原本依賴網域的規則無法穩定命中。啟用 DNS 後，應讓需要接管的請求真正進入其監聽位址；僅在設定中寫入 dns.enable: true，但系統仍向其他伺服器發送查詢，並不能形成完整的解析鏈。

listen 指定 DNS 服務的監聽位置與連接埠。桌面 GUI 的 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
  use-hosts: true
  respect-rules: true
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  proxy-server-nameserver:
    - https://223.5.5.5/dns-query
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "+.local"

default-nameserver、nameserver 與代理節點網域

nameserver 是主要解析上游，可以填寫傳統 UDP 位址，也可以填寫加密 DNS 位址。當加密 DNS 本身也是網域時，核心必須先知道該網域對應的位址，因此需要 default-nameserver 完成引導解析。引導伺服器通常填寫可直接存取的 IP 位址，避免出現「需要解析上游網域才能存取上游，而解析又依賴該上游」的迴圈。

proxy-server-nameserver 用於解析代理伺服器本身的網域。這條路徑應優先選擇在目前網路中可直接存取且結果穩定的上游，因為代理節點尚未建立之前，節點網域必須先完成解析。如果將節點網域的解析強制交給只能透過該節點存取的伺服器，同樣會形成啟動依賴迴圈。當節點全部逾時，而 IP 形式的節點正常時，應優先檢查這一層。

respect-rules 讓 DNS 查詢參考規則選擇出口，適合需要對解析流量也進行分流的設定。不過啟用後必須確保引導解析、代理節點解析與主要解析之間沒有互相等待。設定複雜時，先關閉規則感知並驗證基本解析，再逐步啟用，比一次加入全部 DNS 選項更穩妥。

Fake-IP 與 Redir-Host 的差異

fake-ip 模式會從保留位址池回傳一個映射位址，應用程式連線至該位址後，核心會依映射表還原原始網域並執行規則。這能讓網域資訊在連線階段持續保留，也減少應用程式先取得真實位址再發起連線時造成的分流偏差。位址池只在本機或受控網路內作為映射使用，不是目標網站的真實位址；看到保留網段結果不代表 DNS 解析故障。

redir-host 回傳真實解析位址，兼容依賴真實 IP 的區域網路服務、部分遊戲與特殊網路檢測，但網域與後續連線的關聯能力相對受限。遇到印表機探索、區域網路主機名稱、裝置投放或特定應用程式登入異常時，可以先將對應網域加入 fake-ip-filter，不必直接切換整個增強模式。過濾清單應盡量精確；範圍過大會讓大量網域繞過映射，降低網域規則的一致性。關於映射流程與篩選範圍，可繼續閱讀Fake-IP 模式原理詳解。

nameserver-policy 的定向解析

nameserver-policy 可以讓特定網域使用指定的 DNS 上游。例如將內部網域交給區域網路 DNS，某類公共網域交給另一組解析器。策略鍵可以使用網域規則集合或網域匹配形式，值可以是一個上游，也可以是一組上游。它解決的是「某類網域應在哪裡解析」，不是「連線最終經由哪個代理」；連線出口仍由 rules 與策略組決定。

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query
  nameserver-policy:
    "+.corp.example":
      - 192.168.1.1
    "rule-set:private-domain":
      - 192.168.1.1

04 / PROXY OBJECTS

代理節點欄位：連線物件、協定參數與提供器

節點物件的共同骨架

proxies 是節點物件清單。每個物件至少需要名稱、類型、伺服器位址與連接埠，驗證、傳輸與加密欄位則由協定決定。name 是其他區塊引用節點的唯一識別名稱，不應出現重複名稱；當兩個節點同名時，介面顯示與策略引用都會變得難以判斷。server 可以是 IP 或網域，填寫網域時也要確保 DNS 區塊能在節點連線前解析它。

協定欄位不能跨類型照搬。某個欄位在一種協定下有效，不代表放入另一種節點也會產生相同效果；未知欄位可能被忽略，也可能導致設定檢查失敗。整理訂閱時應保留協定要求的必要參數，刪除轉換鏈遺留但核心不識別的裝飾欄位。節點連線失敗時，先核對類型、伺服器、連接埠與驗證四項，再檢查 TLS、傳輸層與伺服器名稱，不要先修改策略組或規則。

proxies:
  - name: "辦公室 SOCKS"
    type: socks5
    server: 192.168.1.10
    port: 1080
    username: "proxy-user"
    password: "your-password"
    udp: true

  - name: "範例 Shadowsocks"
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

TLS 與伺服器名稱

具備 TLS 的協定通常涉及 tls、伺服器名稱與憑證驗證。伺服器名稱用於握手階段選擇憑證與虛擬主機，它可能與節點連線位址相同，也可能由伺服器另外指定。連線位址寫成 IP 時，若伺服器憑證簽發給網域，就更需要正確填寫伺服器名稱。憑證錯誤不應透過長期關閉驗證來掩蓋，應先核對系統時間、節點資訊、伺服器名稱與中間網路。啟用代理後遇到瀏覽器憑證提示，可以參考HTTPS 憑證錯誤逐項排查。

WebSocket、gRPC 等傳輸層還會帶有路徑、Host 或服務名稱。這些值由伺服器部署決定，用戶端無法靠猜測取得。路徑中的斜線、大小寫與空白字元都可能影響握手，訂閱轉換時也要避免錯誤展開巢狀欄位。若 TCP 已能連線至伺服器連接埠，但很快被關閉，日誌出現握手失敗，排查重點通常應從網路可達性轉向 TLS 與傳輸層參數。

proxy-providers 管理動態節點集合

節點數量較多或來源需要定期更新時，可使用 proxy-providers。提供器負責從檔案或遠端位址讀取節點，並可設定健康檢查；策略組透過 use 引用整個提供器，而不是將每個節點名稱手動寫入 proxies。這種結構能減少訂閱更新後策略組遺漏新節點的問題，也方便將不同來源拆分成獨立集合。

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

proxy-groups:
  - name: "自動選擇"
    type: url-test
    use:
      - primary
    url: https://www.gstatic.com/generate_204
    interval: 300

path 是提供器內容的本機快取位置，執行使用者必須對其父目錄具備寫入權限。在容器與系統服務環境中，相對路徑以程序工作目錄為基準，不一定是設定檔所在目錄；出現提供器下載成功但快取寫入失敗時，應檢查實際工作目錄與掛載路徑。遠端位址中的存取參數屬於敏感設定，分享日誌或設定片段前務必移除。

健康檢查只回答測試位址能否經由該節點完成請求，不代表所有目標都能存取，也不等同於頻寬測試。檢查位址應穩定、回應內容小，並與日常流量的協定需求相近。檢查頻率過高會持續建立連線，節點數量多時會增加額外資源消耗；頻率過低則可能讓故障狀態更新不及時。應依節點數量與切換需求取得平衡，而不是單純追求更短間隔。

05 / POLICY LAYER

策略組欄位：選擇、測速、故障轉移與巢狀結構

策略組是規則與節點之間的調度層

規則通常不會直接指向某個固定節點，而是指向策略組。如此一來節點變動時，只需調整組內成員或目前選擇，不必重寫整套規則。select 組由使用者手動選擇成員；url-test 依測試結果自動選擇；fallback 按成員順序尋找可用項目；load-balance 在多個可用成員之間分配連線。不同類型解決的問題不同，不能只根據介面顯示的延遲判斷哪一種較適合。

proxies 清單可以放入節點，也可以放入另一個策略組，還可以使用 DIRECT 與 REJECT 等內建策略。巢狀結構能將「業務分類」與「節點選擇」分開，例如串流媒體規則指向「媒體服務」，媒體服務再引用「節點選擇」。但巢狀層級過深會增加判斷成本，甚至形成循環引用。設計時應確保依賴方向單向向下，任何組都不能直接或間接包含自身。

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

  - name: "自動選擇"
    type: url-test
    proxies:
      - "範例節點"
      - "備用節點"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80

  - name: "故障轉移"
    type: fallback
    proxies:
      - "範例節點"
      - "備用節點"
    url: https://www.gstatic.com/generate_204
    interval: 300

  - name: "媒體服務"
    type: select
    proxies:
      - "節點選擇"
      - DIRECT

如何理解測速結果

url-test 測量的是用戶端經由節點存取指定測試位址的完成時間，包含建立連線與請求回應，並不是所有網站的通用延遲。測試位址所在網路、節點通往該位址的路由以及本機 DNS 都會影響結果。某個節點測試值較低，實際下載卻較慢，可能是頻寬、壅塞、目標站路由或連線複用差異造成，而不是策略組計算錯誤。速度問題可依節點、線路與本機設定三個層面分別驗證。

tolerance 用於避免兩個結果接近的節點頻繁切換。當新結果只比目前節點略好時，維持現有連線通常比反覆重新選擇更穩定。interval 控制週期檢查，lazy 可讓不活躍的策略減少測試。參數應依使用方式調整：桌面裝置偶爾連線與長時間運作的路由器，其資源預算不同，節點數量也會直接放大健康檢查的請求量。

fallback 與 load-balance 的界線

fallback 重視順序與可用性，前面的成員可用時就維持使用，適合主備關係明確的線路。它並非以最低延遲為唯一目標，因此備用節點延遲更低也不一定會被選中。load-balance 面向多連線分配，不等於將單一下載連線拆分到多個節點；單個 TCP 或 UDP 工作階段通常仍維持固定出口，以免來源位址變動破壞工作階段。

負載平衡策略還要考量同一目標是否需要固定出口。登入、付款、驗證碼或對來源位址敏感的服務，如果相鄰請求落到不同節點，可能觸發重新驗證。此時應使用能維持目標映射的策略，或讓相關網域進入固定節點組。對一般使用者而言，清楚的手動選擇組搭配一個自動測速組，通常比多層負載平衡更容易維護。

名稱設計會影響長期維護

策略組名稱既會出現在規則結尾，也會出現在用戶端介面。建議依用途命名，例如「節點選擇」「故障轉移」「媒體服務」「即時通訊」，不要把節點地區、協定與業務用途全部塞進同一個過長名稱。規則提供器與策略組之間可以一對多或多對一，但名稱應保持穩定；頻繁重新命名會讓舊覆寫、腳本與本地規則同時失效。

訂閱提供的策略組可能在更新時被重建。本地需要長期保留的組，應放在用戶端支援的覆寫層，並明確指定插入位置。若某條規則指向本地組，而覆寫執行順序晚於規則合併，最終設定中可能暫時出現未定義引用。檢查時不要只查看某個片段是否存在，而要確認最終檔案中策略組已完成定義，且定義位於核心載入同一份設定的範圍內。

06 / RULE ENGINE

規則語法：由上至下匹配，首條命中即生效

規則順序就是實際優先級

rules 是有序清單。連線從第一條開始檢查，遇到第一條匹配規則後立即採用該規則指定的策略，後續規則不再參與。因此，精確網域與需要特別處理的業務通常放在前面，較寬的網域後綴、IP 網段與地區集合放在中間，MATCH 放在最後接住其餘連線。將寬範圍規則提前，是「明明寫了規則卻不生效」的主要原因之一。

規則通常由類型、匹配值與策略名稱組成，使用英文逗號分隔。策略名稱必須對應已定義的策略組、節點或內建策略。部分規則還可以附加選項，例如 IP 規則使用 no-resolve，表示匹配時不為了取得位址而額外觸發解析。規則中的逗號屬於結構分隔符，包含特殊內容時不能單純依賴 YAML 引號改變 Clash 的規則解析方式。

rules:
  - DOMAIN,api.example.com,節點選擇
  - DOMAIN-SUFFIX,example.com,節點選擇
  - DOMAIN-KEYWORD,example,節點選擇
  - PROCESS-NAME,example.exe,DIRECT
  - DST-PORT,22,DIRECT
  - 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 只要網域包含指定片段就可能命中，涵蓋範圍最廣，也最容易誤傷。可以使用後綴規則時，不應為了少寫幾行而改用關鍵字規則。例如關鍵字過短，可能匹配到與目標服務無關的網域。

網域匹配仰賴核心在連線階段得知原始主機名稱。HTTP、TLS 的伺服器名稱、Fake-IP 映射或流量嗅探都可能提供網域資訊；如果應用程式直接連線至 IP，網域規則自然無法命中。此時需要判斷應用程式本身的行為，而不是重複加入同一網域的多種寫法。啟用流量嗅探可以補充部分連線的網域識別，但它有適用的協定與連接埠範圍，也不應取代正確的 DNS 接管。

IP、連接埠與程序規則

IP-CIDR 與 IP-CIDR6 依目標位址範圍匹配，適合區域網路、保留位址與明確的服務網段。公共服務的位址可能變動或由多個業務共用，手動維護大量公共 IP 往往不如網域或規則集合穩定。GEOIP 依位址資料庫分類，結果取決於本機資料檔；資料過舊時，新分配的位址可能落入預期外的分類，因此資料庫更新也是規則維護的一部分。

DST-PORT 依目標連接埠匹配，無法區分同一連接埠上的不同網站。現代 Web 流量大量共用 443 連接埠，將整個連接埠交給某個策略通常過於寬泛。程序規則可依程式名稱或路徑匹配，但支援情況與作業系統、執行權限及接管方式有關：閘道裝置看不到終端上的程序，部分沙盒應用程式也無法提供完整程序資訊。跨平台設定不應完全依賴程序規則建立關鍵分流。

rule-providers 拆分大型規則集

rule-providers 將規則內容放入本機檔案或遠端資源，主規則清單透過 RULE-SET 引用。提供器需要宣告行為類型、格式、快取路徑與更新間隔。domain 類型用於網域集合，ipcidr 用於位址網段，classical 可包含多種經典規則。行為類型必須與檔案內容相符，否則即使下載成功，也可能無法如預期解析。

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

  private-ip:
    type: file
    behavior: ipcidr
    format: yaml
    path: ./rules/private-ip.yaml

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,private-ip,DIRECT,no-resolve
  - MATCH,節點選擇

規則提供器更新失敗不一定會讓核心立即停止運作，既有快取仍可能繼續使用。因此「設定載入成功」與「規則已更新」是兩回事。排查新增網域未命中時，要檢查提供器狀態、快取檔案修改時間、下載回應內容以及行為類型。遠端資源若回傳網頁錯誤頁而非規則檔案，網路請求可能顯示成功，但解析階段仍會失敗。

結尾策略體現設定的預設立場。以 MATCH,節點選擇 收尾，表示未分類流量交給代理選擇；以 MATCH,DIRECT 收尾，則表示只有明確列出的目標使用代理。兩種設計都可以成立，關鍵在於規則庫涵蓋範圍與使用者預期一致。修改結尾策略會影響所有未命中的連線，應單獨驗證，不要將它當成修復某個網站的臨時開關。

07 / MERGE LAYERS

覆寫與合併：訂閱更新後保留本地設定

先辨識設定的來源層級

圖形化用戶端中的最終設定通常由多個來源組成：遠端訂閱提供節點與基礎策略，本地覆寫修改通用欄位或新增規則，用戶端本身的設定再決定系統代理、TUN、控制連接埠等執行參數。介面上的「訂閱內容」往往只是其中一層。要判斷某個欄位為何被改寫，必須了解合併順序，以及同名欄位發生衝突時採用覆蓋、追加還是深度合併。

不同用戶端對覆寫的命名與能力並不完全相同。有些支援 YAML 片段，有些支援腳本，有些則區分前置規則與後置規則。遷移用戶端時，不應直接假定舊覆寫能原樣執行。Clash Plus 適合作為一般使用者的首選圖形化入口；需要更換其他用戶端時，可在下載頁依平台比較 Clash Verge Rev、FlClash、Clash Nyanpasu、Clash Meta for Android、Surfboard 與封存用戶端。

映射覆蓋與清單追加不是同一種操作

對 mode、log-level、dns.enable 這類單值欄位，覆寫通常以新值取代舊值。對 rules、proxies、proxy-groups 這類清單，直接覆蓋會刪除訂閱原有內容，直接追加又可能讓新規則落在 MATCH 之後而永遠無法命中。因此修改清單時必須明確指定位置：自訂精確規則通常插入寬範圍規則之前，兜底規則則始終保留在最後。

映射的深度合併也有其界線。若只想新增一個 fake-ip-filter 項目，但合併器卻替換整個 dns 物件，原有的 nameserver 與監聽欄位就會消失。反過來，若預期完全替換 DNS，而工具執行逐鍵合併，訂閱遺留的策略欄位仍會存在。使用覆寫前應先了解用戶端如何處理物件與陣列，並透過最終設定確認結果，而不是只看覆寫片段本身的語法是否正確。

# 本地覆寫片段示意
mode: rule
log-level: info

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

rules:
  - DOMAIN,internal.example,DIRECT
  - DOMAIN-SUFFIX,example.com,節點選擇

規則插入位置決定覆寫是否有效

假設訂閱結尾已有 MATCH,節點選擇，本地規則若直接追加到清單尾端，永遠不會被執行。正確做法是在兜底規則之前插入，或由覆寫工具提供「前置規則」功能。若訂閱包含較寬泛的 DOMAIN-SUFFIX、GEOIP 或規則集，本地精確例外也要放在這些寬範圍規則之前。規則本身沒有明確的優先級數字，位置就是優先級。

策略組覆寫還要處理成員引用。新增一個名為「開發服務」的組並不夠，規則必須指向它，而它內部引用的「節點選擇」也必須存在於最終設定中。訂閱方重新命名策略組後，本地覆寫可能仍成功合併，卻在載入時出現未定義策略。更穩妥的做法是減少對訂閱自訂名稱的依賴，或在每次訂閱結構變更後檢查最終引用圖。

腳本覆寫適合條件式修改，但要控制複雜度

腳本可以遍歷節點、重建策略組，或依名稱插入規則，適合處理訂閱每次更新都可能變動的清單。不過腳本也引入新的失敗層：欄位可能不存在、節點名稱可能含特殊字元、用戶端升級後輸入結構可能變化。腳本應先檢查物件類型與陣列是否存在，避免假定所有訂閱都具有相同骨架；發生例外時應保留原設定並輸出明確日誌，而不是回傳半成品。

複雜腳本需要像一般程式碼一樣進行版本管理與測試。每次修改只解決一類問題，保留輸入範例，並處理空節點清單、缺少策略組、已有同名規則等邊界情況。若需求只是修改連接埠或新增兩條規則，YAML 覆寫通常比腳本更透明。只有當重複操作確實無法透過宣告式片段表達時，才使用腳本。

直接執行核心時的合併策略

直接執行 mihomo 時，可以在部署流程中使用範本或設定產生工具完成合併，但產生結果仍應是一份可獨立檢查的 YAML。服務啟動前先產生至暫存檔，檢查成功後再以原子方式替換正式設定，可避免合併中斷留下半份檔案。路由器與旁路由環境的目錄權限、持久化分割區與開機順序也會影響規則下載與快取復原，相關架構可參閱路由器與旁路由部署概覽。

08 / VALIDATION

檢查與排錯：從載入失敗到分流異常

先進行靜態檢查，再查看執行日誌

設定故障應依層級處理。第一層是 YAML 能否解析，包括縮排、冒號、清單與引號；第二層是 Clash 設定語意能否成立，包括節點類型、必要欄位、策略引用與規則格式；第三層才是執行時網路問題，例如 DNS 無法連線、節點握手失敗、系統代理未啟用或透明代理路由缺失。若第一層尚未通過，就不必測試節點延遲或修改防火牆。

直接執行核心時，可以使用設定檢查參數驗證指定目錄中的設定。實際命令中的可執行檔路徑與設定目錄應依部署位置調整。圖形化用戶端通常也提供設定檢查、重新載入或日誌入口；如果介面只顯示「載入失敗」，應開啟詳細日誌定位具體欄位。檢查前先儲存檔案，確認編輯器沒有寫入定位字元或不可見字元。

mihomo -t -d /path/to/config-directory
mihomo -d /path/to/config-directory

檢查命令通過，只代表設定結構能被核心接受，不代表所有遠端節點、DNS 上游與規則提供器都能存取。啟動後還應觀察提供器更新、DNS 請求、連線撥號與規則命中。將日誌層級暫時設為 debug 可提供更多上下文，但分析時要圍繞一次明確請求，避免在大量背景連線中尋找線索。

載入失敗的常見分支

錯誤指向某一行時，實際原因可能位於上一行，例如遺漏引號導致後續內容被錯誤解析，或上一層縮排已經改變。應從報錯行向上檢查至最近的頂層欄位。出現「找不到策略」這類錯誤時，搜尋規則結尾的名稱，再搜尋策略組定義，逐字比較空格與符號。出現重複名稱時，不僅要檢查手動撰寫的節點，也要考慮提供器展開後是否與靜態節點同名。

設定在一個用戶端可用，換到另一個用戶端後失敗，通常與支援欄位、核心能力或覆寫格式有關。應先匯出最小設定，只保留一個基礎節點、一個選擇組與兩條規則，確認目標用戶端能載入後，再逐區塊恢復。不要透過連續刪除隨機欄位碰運氣；每輪只變更一個區塊，並記錄變化出現在語法檢查、啟動還是實際連線階段。

連線成功但頁面無法開啟

節點測試成功而網頁無法開啟時，應將 DNS、規則與應用程式接管分開驗證。先使用明確指定 mixed-port 的命令存取簡單位址，確認代理連接埠正常；再檢查瀏覽器或系統代理是否指向同一位址；接著觀察目標網域命中了哪條規則。如果日誌完全沒有該應用程式的連線，問題位於接管層；如果有連線但規則不符，問題位於規則或網域識別；如果策略正確但撥號失敗，再回頭檢查節點與傳輸層。

部分網站正常、部分網站長時間等待時，要注意 IPv6、UDP、HTTP/3 與 MTU。應用程式可能優先嘗試 IPv6 或 QUIC，失敗後才回退至其他路徑。TUN 環境中的 MTU 過大，也可能讓小型請求正常而大型回應卡住。排查時可以暫時關閉單一功能進行對照，但確認原因後應回到網路條件與協定支援上修正，不要長期堆疊彼此矛盾的臨時開關。

TUN 與透明代理的額外檢查

TUN 接管依賴虛擬網卡、路由與權限。桌面系統上，用戶端可能需要系統授權才能建立網卡；Linux 上還涉及核心能力、轉送設定與策略路由。TUN 顯示已開啟但應用程式流量沒有進入日誌時，應查看預設路由與排除網段，而不是只重新啟動核心。區域網路網段、虛擬機器網路、容器網路與公司內部網路通常需要明確直連，否則存取本地服務時可能被錯誤送入代理。

閘道透明代理還要防止核心自身流量再次被轉送。節點連線、DNS 上游請求與規則下載若重新進入同一條透明代理鏈，會形成迴圈。常見處理方式是依執行使用者、程序標記或路由標記排除，但具體方法取決於 nftables、iptables 與系統路由設計。設定檔只能提供監聽連接埠與 TUN 參數，不能取代作業系統層的完整迴圈排除。

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

建立可重複的排錯記錄

有效的排錯記錄至少包括：目前用戶端或核心的執行方式、設定來源、故障出現在哪個步驟、一次請求對應的日誌、已驗證正常的環節，以及最近的變更。分享設定片段前應移除訂閱位址、驗證資訊、控制憑證與節點密碼，但保留欄位結構、策略名稱與規則順序。只提供「不能用」或一大段無關日誌，很難判斷錯誤層級。

修復完成後，清除暫時調高的日誌層級、測試規則與繞過項目，再重新載入並複測。對於長期運作的路由器或伺服器，還應重新啟動服務，驗證開機流程、工作目錄與快取權限，避免目前終端工作階段可用而系統服務失敗。區域網路共享情境可繼續查閱mixed-port 與 allow-lan 設定指南，確認監聽位址、防火牆與裝置代理參數位於同一條鏈路。