Clash YAML 設定參考

一、YAML 結構與設定入口

先確認要修改的是哪個檔案

重點是：編輯器顯示儲存成功，不代表核心已採用新內容。圖形介面用戶端通常會將設定分為訂閱下載的原始檔、使用者填寫的覆寫片段，以及合併後交由核心載入的執行檔。訂閱更新會重新產生原始檔，直接修改其中的規則，下次更新時可能就會消失；修改執行檔也可能被用戶端的啟動流程覆蓋。請先在設定頁確認目前啟用的項目，再找到設定預覽、執行設定或匯出設定的入口，核對目標欄位的最終值。

本頁範例依用途分開呈現，請勿直接將所有片段首尾拼接。單一 YAML 文件的頂層應為映射；dns、proxies、proxy-groups、rules 是不同的鍵。在同一層重複寫入兩個 dns，不代表系統會自動合併：解析器可能拒絕載入，也可能只保留後者。實際編輯時，請找到既有區段並在其中調整。以下最小設定僅用來驗證結構與本機監聽，所有流量皆直連，不含可用的代理線路。

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

proxies: []
proxy-groups: []

rules:
  - MATCH,DIRECT

縮排、清單與字串的基本規則

縮排決定欄位的層級，建議統一使用兩個空格，不可用定位字元取代。冒號後加空格表示鍵值分隔；連字號後加空格表示清單項目。rules 底下的每條規則都是字串清單項目，而 proxies 底下的每個節點通常是包含多個欄位的映射。節點的 name、type、server 必須位於相同縮排層級；若將 port 多縮排一層，可能直接造成解析錯誤，而非變更連接埠。

包含井字號、冒號後接空格等特殊組合的文字，最好用引號括起來。密碼和識別碼尤其應視為字串，避免純數字被解析成數值，或前導零遭到刪除。單引號通常適合保留含反斜線的一般文字；雙引號則會解析跳脫序列。若字串中確實需要雙引號，必須正確跳脫。請勿從通訊軟體複製含全形冒號、彎引號或不可見縮排的設定，外觀相似不代表解析結果相同。

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

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

rules:
  - MATCH,手動選擇

空值、布林值與跨區段參照

false 是布林值，"false" 是字串，不能仰賴核心自動修正型別。[] 表示空清單，{} 表示空映射，而鍵後未填內容通常表示空值，三者不可任意互換。節點名稱、策略組名稱與規則目標彼此互相參照，建議統一命名並避免重複。名稱中不要使用逗號，因為規則以逗號分隔參數；可以使用易讀的中文名稱，但所有參照處都必須完全一致。

檢查設定時要分成兩個層次：YAML 能成功解析，只代表語法結構成立；核心能載入，才表示欄位型別、協定支援與名稱參照大致有效。即使載入成功，也不代表遠端位址、密碼或規則設定符合預期。不要一次加入複雜的錨點、合併鍵與範本語法，這些功能會放大不同用戶端之間的解析差異。先以一般映射和清單確認設定可運作，再考慮減少重複；不確定核心身分時，先查看用戶端的「關於」頁面或啟動記錄，不要只憑介面名稱判斷相容性。

二、通用欄位：監聽連接埠與代理模式

連接埠只負責接收流量，不代表線路速度

mixed-port 會在同一個監聽連接埠接收 HTTP 與 SOCKS 代理請求，適合讓瀏覽器和命令列工具共用同一個入口。port 是獨立的 HTTP 代理連接埠，socks-port 則是獨立的 SOCKS 連接埠，兩者不必都設定。一般桌面使用者可先保留混合連接埠，避免多個監聽入口造成混淆。連接埠數值只是本機服務位址的一部分，將它從一個數字改成另一個數字，不會讓遠端代理線路變快。

修改連接埠後，請重新載入設定並確認新監聽已建立，再將系統代理、瀏覽器手動代理或終端機環境變數同步改為新值。舊的環境變數不會隨 YAML 自動更新，已開啟的終端機也可能仍保留原設定。桌面用戶端可能以介面中的連接埠選項覆蓋檔案設定，因此應以執行設定和監聽記錄為準。遇到連接埠遭占用時，先找出占用的程序，確認是否為另一個用戶端執行個體；不要為了釋出連接埠就直接終止不明的系統程序。

mixed-port: 7891
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false

規則、全域與直連模式的差異

mode: rule 表示依照規則清單決定出口，日常分流通常使用此模式。global 表示交由全域策略處理進入核心的流量，但仍須確認全域策略選擇了哪個出口；direct 則使用直連。這裡的關鍵是進入核心的流量：未設定系統代理、未使用明確代理，也未由 TUN 接管的應用程式，不會只因切換成全域模式就自動走代理。模式設定與流量入口是兩個不同層面的選項。

切換模式適合用來對照測試，不適合拿來掩蓋規則錯誤。如果規則模式失敗、全域模式成功，應檢查規則命中、策略組選擇或 DNS，而不是長期停留在全域模式就結束排錯。如果兩種模式都失敗，優先檢查節點、驗證資訊、監聽狀態與網路連線。既有的長連線可能仍沿用舊出口，切換後請用新連線驗證。更詳細的差異可參考疑難排解中的代理模式說明，避免將切換模式誤認為線路最佳化。

區域網路監聽與控制介面應分開管理

allow-lan: false 適合只讓本機應用程式使用代理。若要讓其他裝置使用代理，除了允許區域網路連線，也要檢查 bind-address、主機防火牆、無線網路隔離設定與裝置連線位址。其他裝置應填入執行用戶端那台電腦的區域網路位址，不可使用裝置本身的迴路位址。開放監聽會擴大可存取範圍，應僅在可信任的網路中使用，並搭配驗證或存取控制，不要直接將連接埠暴露在公用網路。

external-controller 是管理介面，不是瀏覽器的代理位址；將系統代理指向控制連接埠，無法建立正常的代理連線。管理介面應優先綁定迴路位址，若需遠端存取，再另外規劃驗證方式與網路界線。log-level: debug 可在短時間內協助排錯，但會產生更多資訊，分享記錄前請遮蔽訂閱網址和驗證資料。ipv6 與位址處理有關，不能取代網路本身的 IPv6 連線能力；未確認測試環境前，不要同時調整它和 DNS 的多個選項。

程序定位與修改順序詳見7890 連接埠占用排查。重點不在於換成哪個數字，而是確保監聽位址、入口協定與應用程式設定三者一致，並以新請求確認變更確實生效。

三、DNS：解析入口與 fake-ip

先分清核心解析與系統解析

DNS 設定不只是填入一個伺服器位址，還需要釐清三件事：誰將網域名稱交給核心解析、核心使用哪個上游取得實際位址，以及解析結果如何影響後續連線。dns.enable 會啟用內建解析服務，listen 用來指定監聽位置，但不會自動讓所有系統請求改走這個服務。系統 DNS、瀏覽器安全 DNS、應用程式自行解析與 TUN 劫持可能同時存在；設定檔中有 DNS 設定，不足以證明目標請求實際經過它。

以下示範常見的 fake-ip 結構，監聽本機的高位連接埠，方便單獨驗證。這不是完整的透明代理方案，也不會自動變更系統解析器。default-nameserver 用來解析上游 DNS 伺服器的網域名稱，應選擇可直接連線的 IP 位址型解析器；nameserver 則負責一般網域查詢。範例中的上游必須能從目前網路連線，否則請依網路環境更換，不要將特定位址視為適用所有地區的固定答案。

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"
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query

fake-ip 不代表解析失敗，也不負責加密

enhanced-mode: fake-ip 會替查詢指派合成位址並維護網域對應，讓後續連線更容易保留網域資訊。結果以 198.18 開頭，不一定表示異常；關鍵在於連至合成位址的流量是否仍由同一套代理接管。如果 DNS 回傳 fake-ip，但後續流量繞過核心直接送出，通常就無法建立連線。因此必須讓解析入口與連線入口相互配合，不能只在系統中單獨指定解析服務。

fake-ip-filter 可讓指定網域略過合成位址指派，常用於確實需要實際位址的區域網路服務。不要隨意將大量公用網域加入過濾清單，否則會失去網域對應的便利，也會增加排錯難度。redir-host 會回傳實際解析結果，是另一種運作方式，但不代表一定更快或更安全。遇到相容性問題時可逐項比較，先記錄受影響的網域、應用程式與存取路徑，再判斷是否需要新增例外。

nameserver、fallback 與指定解析

fallback 不只是順位第二的伺服器。完成設定後，核心會搭配 fallback-filter 等條件判斷採用哪一組結果；不同選項涉及網域、位址範圍與地理資訊，實際行為請以目前使用的核心文件為準。只複製 fallback 設定，卻不了解篩選條件，可能增加查詢量，或取代原本可用的結果。先以單一可連線的上游確認基本解析正常，再根據實際需求加入分流，不要一開始就堆疊多個公用解析服務。

mihomo 的 nameserver-policy 可依網域指定解析器，適合將內部網域交由區域網路 DNS 處理。代理伺服器本身的網域解析可能也會用到 proxy-server-nameserver，避免在建立代理連線前就依賴該代理，形成循環。使用加密 DNS 只會保護相應的 DNS 傳輸，不會自動讓業務連線走代理；是否遵循路由規則、上游如何連線，應依目前核心支援的欄位逐項確認。

dns:
  enable: true
  listen: "127.0.0.1:1053"
  enhanced-mode: fake-ip
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    "+.home.arpa":
      - 192.168.1.1
  proxy-server-nameserver:
    - 223.5.5.5

上例是另一種 DNS 區段的示意，192.168.1.1 必須換成實際的內部解析器；不要將它與前一個範例一併貼上，造成兩個頂層 DNS 區段。TUN 的 dns-hijack 位於 tun 底下，不屬於 dns，而且通常無法接管應用程式自行發出的 HTTPS DNS。排錯時請分別測試核心監聽、系統解析與瀏覽器行為，並清除快取或建立新連線，避免舊結果影響判斷。

四、代理節點：協定欄位與提供器

通用欄位相同，不代表協定參數可以通用

proxies 是本機節點定義清單。最常見的通用欄位是 name、type、server 與 port：名稱供策略組參照，類型決定協定解析方式，伺服器與連接埠則指定連線目標。server 通常只填網域名稱或 IP，不要加上 https://、路徑或訂閱查詢參數。代理節點的連接埠是遠端服務連接埠，與本機的 mixed-port 不需要相同，請勿將兩者混為一談。

協定專用參數必須由服務提供者提供。Shadowsocks 需要相符的加密方式與密碼；Trojan 通常需要密碼與 TLS 相關參數；VMess、VLESS 則會用到相應識別資料與傳輸設定。不能只將 type 從一種協定改成另一種，就期待原節點仍可使用。傳輸層也必須相符：WebSocket 路徑、請求標頭、gRPC 服務名稱等欄位，只有伺服器確實設定了相應傳輸方式才有作用。多填欄位不會提升相容性。

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

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

TLS 名稱與 UDP 能力不能只靠開關補足

sni 是 TLS 交握時使用的名稱，可能與連線位址相同，也可能由服務提供者另行指定。遇到憑證錯誤，應先檢查裝置時間、伺服器名稱、憑證有效性與連線是否遭到替換，不應將 skip-cert-verify 設為 true 當成一般解法。保留憑證驗證可以明確揭露名稱不符等問題；若連最初的 TCP 連線都無法建立，修改 SNI 或憑證選項通常也無法解決位址無法連線的問題。

udp: true 只代表設定允許使用相應功能，不代表伺服器、協定、線路與應用程式入口都已支援 UDP。瀏覽器可以開啟網頁，但遊戲或語音失敗時，應檢查實際使用的傳輸方式與流量接管路徑。反過來說，測速逾時也不能立刻認定所有服務都無法使用；測試目標、請求方式與節點路由可能各不相同。應分別判斷交握失敗、驗證失敗與遠端連線失敗，避免將所有錯誤都歸咎於節點失效。

proxy-providers 負責載入節點集合

proxy-providers 用來將節點集合交由核心載入，再由策略組透過 use 參照。HTTP 提供器的 url 是資源位址，path 是快取位置，interval 通常以秒為單位設定更新間隔。提供器資源與完整用戶端訂閱不是相同格式：常見節點提供器必須包含 proxies 清單；如果回應內容是網頁登入畫面或其他格式，只改副檔名並不會讓它變成有效的 YAML。

proxy-providers:
  remote-nodes:
    type: http
    url: "https://example.com/proxies.yaml?token=xxxx"
    path: ./providers/remote-nodes.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "訂閱選擇"
    type: select
    use:
      - remote-nodes

範例位址僅用來示範結構，請替換為實際提供器資源；若訂閱已由用戶端設定頁管理，通常不必再手動建立另一套更新機制。先確認服務提供者提供的是完整設定、節點清單還是 URI 集合，再選擇相應的匯入方式。核心會依工作目錄解讀相對快取路徑，不一定以編輯器開啟的資料夾為基準；更新失敗時，查看用戶端資料目錄與權限，會比反覆移動 YAML 更有幫助。

驗證資訊屬於敏感資料，截圖與求助記錄只保留網域、錯誤類型及必要欄位，不要公開完整訂閱連結。節點名稱更新後，手動寫死的策略組參照可能失效；使用提供器參照可減少逐一維護，但仍須處理篩選條件與沒有可用節點的情況。訂閱能下載只代表資源取得成功，不能取代節點連線測試，也不代表目前核心支援其中所有協定。

五、策略組：手動選擇、測速與故障切換

先建立清楚的參照關係

策略組是規則與實際出口之間的選擇層。規則可以指向策略組，而策略組可包含節點、其他策略組或內建目標。更換節點時，就不必修改每條網域規則。最基本的 select 可供手動選擇，適合先確認哪些線路可用。組內 proxies 填入的是節點或策略組名稱，不是伺服器位址；use 填入的則是提供器名稱。兩者參照的對象不同，名稱只要有一個字拼錯，就可能讓設定載入失敗。

建議將用途與運作方式分開命名，例如「日常出口」代表業務入口，「自動測速」代表選擇方式。日常規則統一指向前者，再由前者選擇測速組、備援組或單一節點。不要讓策略組包含自己，也不要讓多個組互相循環參照。組名避免與內建目標或節點名稱重複；巢狀設定即使可以載入，也不一定容易維護。排錯時層級愈少，愈容易確認實際出口。

proxies:
  - name: "線路 A"
    type: ss
    server: a.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
  - name: "線路 B"
    type: ss
    server: b.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "日常出口"
    type: select
    proxies:
      - "自動測速"
      - "備援切換"
      - "線路 A"
      - "線路 B"
      - DIRECT

  - name: "自動測速"
    type: url-test
    proxies:
      - "線路 A"
      - "線路 B"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: "備援切換"
    type: fallback
    proxies:
      - "線路 A"
      - "線路 B"
    url: https://www.gstatic.com/generate_204
    interval: 300

rules:
  - MATCH,日常出口

自動測速只反映測試請求的結果

url-test 會依測試結果選擇出口；url 是測試目標，interval 控制測試間隔，tolerance 用來減少小幅差異造成的頻繁切換，通常以毫秒計算。不要將測試週期設得太短，特別是使用行動裝置或節點數量較多時，頻繁發送請求會增加網路與電量消耗。選擇穩定且預期回應明確的測試位址，避免使用需要登入、會複雜轉址或限制特定線路存取的頁面。

節點延遲是單次測試請求的觀察結果，不等於影片傳輸量、下載速度或所有網站的回應時間。測試目標可連線，不代表實際服務不會受到地區、帳號或服務政策影響。節點測得的數值較低時，仍應以實際服務驗證，不要單憑測速結果決定整套規則。若組內包含 DIRECT，也要先確認設定目的：讓自動測速在直連與代理之間競爭，可能會選出與預期完全不同的出口。

fallback 與負載平衡各有適用範圍

fallback 通常依清單順序選擇可用項目，重點在故障切換，而非每次尋找延遲最低的節點。排在前面的節點恢復後，新連線如何選擇，仍應依核心實作與目前狀態確認。它不會轉移已中斷的 TCP 工作階段，下載中的工作可能仍須重新連線。將它理解為「主要線路加備援線路」較為恰當，不要以為自動恢復能讓服務完全不中斷。

load-balance 會將連線分配至多個出口，分配方式依具體設定而異，不會直接將多條線路的頻寬相加，讓單一連線變快。有些服務對出口 IP 位址變動很敏感，可能因此要求重新驗證或發生工作階段異常；這類服務適合固定使用穩定的策略組。首次建立設定時，先用手動策略組完成驗證，再加入自動化機制。若手動選取節點仍無法連線，應繼續檢查節點或流量入口，而不是調整測速容差。

用戶端可能會記住策略組上次選取的項目，重新載入後不一定會回到清單第一項。profile.store-selected 等設定、圖形介面的保存機制與組名變更，都可能影響還原結果。排錯時應查看目前選取的項目，不要只看 YAML 的排列順序。透過提供器更新節點時，也要確認篩選後是否仍有可用項目；自動組為空、名稱參照缺失與所有測試都失敗，是三種不同問題，應分別處理。

六、分流規則：比對順序與規則集

規則由上而下比對，先命中就停止

在規則模式下，一般規則依清單順序比對，第一條命中的規則會決定後續出口。最常出錯的不是寫法，而是排列位置：範圍很大的規則若放在前面，後面的精確例外就不會有機會執行。MATCH 是最終兜底規則，應放在一般清單末尾。新增網站例外時，還應確認規則目標存在、策略組選擇正確，並以新連線觀察命中結果；清單中看得到網域，不代表請求實際經過該規則。

DOMAIN 精確比對網域，DOMAIN-SUFFIX 比對網域及其子網域，DOMAIN-KEYWORD 則比對網域中的關鍵字。若要讓特定網站直連，優先使用精確網域或網域後綴，不要只填簡短關鍵字，以免影響無關網域。規則通常不包含 URL 協定、路徑或網頁參數；同一網站也可能呼叫多個資源網域，首頁命中直連不代表圖片、登入與 API 也會使用相同出口。

rules:
  - DOMAIN,printer.home.arpa,DIRECT
  - DOMAIN-SUFFIX,home.arpa,DIRECT
  - DOMAIN-SUFFIX,example.org,日常出口
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,日常出口

IP 規則與 no-resolve 的實際用途

IP-CIDR 依目的位址所屬網段比對，適合內部網路或明確指定的位址範圍。no-resolve 表示此規則不會主動觸發網域解析，不代表整個連線都停用 DNS。若請求已有目的 IP，仍可進行比對；若只有網域名稱且尚未解析，則可能略過該規則並繼續比對後續項目。在所有 IP 規則加入此參數前，請先確認目的是減少查詢，還是必須依解析結果判斷出口。

GEOIP 依賴相應的位址資料庫，GEOSITE 涉及網域分類資料，兩者都與核心支援及資源設定有關。它們不是即時判斷伺服器實際所在地的工具，資料庫更新狀態與共用位址也可能造成誤差。單一服務發生分流錯誤時，以精確規則覆寫通常比大幅調整分類邏輯更穩妥。不要為了省事，就把所有私有位址都交給範圍過廣的公用網路例外，尤其是在企業網路或多個區域網路並存時。

rule-providers 的格式必須符合 behavior

規則提供器可將長清單獨立存成資源，再由主設定透過 RULE-SET 引用。behavior: domain 適用於網域清單，ipcidr 適用於網段，classical 則使用規則類型與參數。資源內容也必須符合 format：不可將純文字清單當成含有 payload 的 YAML，也不可將二進位資源當作文字讀取。若下載成功但解析失敗，請先核對格式與回應內容，再判斷是否為網路問題。

rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,local-domains,DIRECT
  - MATCH,日常出口

對應的 local-domains.yaml 可依照以下範例撰寫。請先建立檔案並確保核心具有讀取權限；相對路徑仍由執行目錄決定。主設定中的目標「日常出口」必須已在策略組中定義；規則提供器檔案只存放比對內容，不必在每一行重複填寫策略名稱。清楚劃分資源用途，比在所有檔案中混寫出口更容易維護。

payload:
  - "+.home.arpa"
  - "printer.example.com"

mihomo 的程序名稱規則等功能也會受到作業系統、權限與流量入口方式影響。某個平台能識別程序，不代表其他平台也有相同效果。應用程式若先自行解析網域，再以 IP 位址連線，依網域比對的規則也可能無法取得必要資訊。排錯時應查看連線詳細資料中的網域、目標 IP、命中規則與實際路徑，先確認輸入資訊是否完整，再決定要調整 DNS、接管方式或規則順序。

七、覆寫與合併：保留訂閱更新能力

分清核心設定與用戶端處理流程

覆寫並不是所有用戶端都共用的 YAML 標準。核心會讀取最終設定，圖形介面用戶端則可能在載入前套用全域設定、個別訂閱設定、合併片段或腳本。Clash Plus、Clash Verge Rev、FlClash 等用戶端的設定入口與優先順序各不相同，不能直接照搬。請先查閱目前用戶端的覆寫說明，再確認設定適用於所有訂閱還是單一設定檔；如果最終產生的檔案欄位與預期不同，應檢查處理流程，而不是反覆修改訂閱原始檔。

常見合併方式包括覆寫純量、遞迴合併映射與取代清單，但沒有必須遵循的統一規則。例如覆寫片段只寫 dns.nameserver，某些工具會保留原 DNS 區段的其他鍵，另一些處理流程則可能取代整個區段。處理 rules、proxies 等清單時更要謹慎：只含一條規則的清單若被當成修補內容提交，可能會直接取代整份規則表。不能只看到「合併」二字，就認定清單一定會附加內容。

# 僅適用於接受一般 YAML 合併片段的用戶端。
# 仍須在用戶端確認映射與清單的合併規則。
mixed-port: 7891
allow-lan: false
log-level: info

dns:
  enable: true
  ipv6: false

規則前置、後置與清單取代

需要新增本機規則時，優先使用用戶端明確提供的規則前置或附加功能，不要猜測某個專屬欄位。前置適合必須優先比對的網域例外；後置則要留意原清單可能已包含 MATCH，加在它後面的普通規則將不會生效。若工具提供的是整份清單取代功能，就必須保留原有規則與兜底項目，並承擔訂閱規則無法同步更新的維護成本。應依照希望保留多少訂閱控制權來選擇方式。

節點與策略組之間也有依賴關係。刪除原節點卻保留舊組參照，會造成找不到目標；用新組名取代舊組名卻未同步修改規則，也會破壞參照。正確的處理順序是先確認最終命名，再同步整理節點、策略組與規則三個層面的關係。如果只想固定特定網站的出口，通常只要新增一條精確規則並參照既有策略組，不必接管整份節點清單。變更範圍愈小，後續訂閱更新就愈不容易產生衝突。

YAML 錨點與合併鍵只能在解析器支援的範圍內重用結構，不會自動提供跨檔案覆寫功能，也不能當成通用的清單附加語法。不同編輯器預覽正常，用戶端仍可能採用不同的解析流程。腳本覆寫雖然更有彈性，還涉及用戶端規定的函式入口、執行順序與錯誤處理；本頁不提供假設所有用戶端都支援的腳本範本。若沒有明確的介面說明，使用一般欄位覆寫會比複製來源不明的腳本更容易驗證。

建立方便還原的設定分層

可將維護內容分成三層：訂閱層負責節點與服務提供者規則，本機層負責連接埠、可信任的內網例外與個人策略，暫存層則僅供排錯使用。暫時調整成功後，應整理至適當的持久層並移除重複鍵。每個覆寫片段都應標明用途，並保留修改前可正常執行的備份。不要同時在介面選項、全域覆寫與訂閱覆寫中設定相同連接埠，否則日後只改其中一處，容易產生「明明儲存了卻沒有變化」的錯覺。

驗證覆寫不能只看檔案是否儲存。先重新載入目前的訂閱，檢視合併後的設定並搜尋目標鍵；接著確認策略組與規則參照都存在，最後以新請求檢查命中情況。之後手動更新一次訂閱，確認修改仍然保留，藉此驗證持久化位置是否正確。若更新後設定消失，應移至用戶端支援的本機層，而不是每次更新後重新手動修改。切換到其他訂閱時也要確認適用範圍，避免全域規則引用的策略組只存在於其中一份訂閱。

多人或多裝置共同維護時，建議記錄「欄位、來源、最終值、驗證方式」四項資訊。不要只記錄選單操作步驟，因為用戶端介面可能會改變；記下最終結構，更容易在升級、移轉與重新安裝後還原。更新後突然無法啟動時，應先檢查最近新增的覆寫與參照關係，再前往故障排除頁面逐項定位。

八、驗證與排錯：從載入到實際請求

先完成解析與核心測試

請依序驗證語法、核心載入、連接埠監聽、節點連線、規則命中，最後才測試特定應用程式。如此每個步驟都有明確的輸入與結果。啟動失敗時，先還原到最近一次能正常運作的設定，避免在有問題的檔案上繼續堆疊修改。使用命令列測試前，請確認呼叫的是目前用戶端所用的核心；系統中的其他舊版執行檔可能不支援新欄位，測試結果不能直接代表用戶端的實際行為。

# 請在設定檔所在目錄執行，命令名稱依本機實際安裝方式調整。
mihomo -t -d . -f ./config.yaml

-f 用來指定檔案，-d 用來指定工作目錄；測試時可能需要讀取提供器快取或相關資源。命令成功執行，表示設定在目前環境中通過基本載入檢查，不代表遠端節點與所有規則資源都正常。若用戶端未提供獨立的命令列入口，也可透過設定檢查與記錄頁面完成相同層級的驗證。不要為了執行一次測試命令，就將核心檔案複製到無人管理的目錄，或額外啟動常駐執行個體。

解析錯誤通常會指出行號，但真正原因可能在前一行，例如字串未閉合、清單項目缺漏或縮排層級改變。先檢查錯誤行附近的完整映射，必要時回到最小結構再逐段加入。若名稱不存在，應檢查節點、策略組與規則之間的參照，不是刪掉錯誤行就算修好；欄位不受支援時，請確認核心身分與欄位適用位置。遇到權限或資源讀取錯誤，應檢查工作目錄，而非修改 YAML 縮排。

用明確代理排除系統接管問題

核心正常啟動後，先透過明確指定的代理發送新請求，暫時排除系統代理與 TUN 造成的影響。以下命令適用於支援這些選項的 curl；在 Windows 環境中可明確使用 curl.exe，避免命令別名造成差異。請將連接埠改為實際監聽值，測試位址也應選擇目前環境預期可連線的目標。單次請求失敗只能證明這條路徑有問題，不能直接認定所有代理功能都失效。

curl --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://example.com/
curl --proxy socks5h://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://example.com/

socks5h 會將網域交由代理端解析，與用戶端先在本機解析再連線的測試方式不同。如果其中一種成功、另一種失敗，應繼續比較解析方式與入口協定，不要立刻更換所有節點。明確代理測試成功但瀏覽器失敗時，優先檢查系統代理、瀏覽器擴充功能、獨立安全 DNS 與舊連線。TUN 情境還需檢查系統路由、授權與其他網路接管軟體，避免兩套工具同時爭用流量入口。

依症狀蒐集必要資訊

求助時請提供作業系統、用戶端名稱、核心身分、故障發生步驟及已遮蔽敏感資訊的相關記錄。另請說明明確代理是否成功、規則模式與全域模式是否有差異，以及是否只有單一目標失敗。這些資訊比一張「逾時」截圖更有幫助。不要只上傳大量 debug 輸出：先擷取故障前後相關記錄，遮蔽驗證資料，再說明每次測試改動了哪個變數。錯誤能穩定重現，才容易判斷修正是否有效。

最後進行一次回歸測試：重新啟動用戶端，確認監聽已恢復；更新訂閱，確認本機覆寫仍保留；切換網路後重試目標服務，檢查解析快取與策略組選擇。排錯完成後，將記錄層級恢復為日常設定，移除暫時放寬的選項與重複規則。維護設定的目標不是欄位愈多愈好，而是每個欄位都說得出用途，每次修改都能驗證結果。如需重新梳理連線流程，請返回使用說明；如需更換用戶端，請參閱下載中心的作業系統與架構選項。