Clash 設定檔參考

YAML 結構與檔案範圍

Clash 設定檔通常採用 YAML 格式，常見檔名為 config.yaml，但檔名本身不會決定用途。實際載入的檔案取決於用戶端目前選取的設定，或核心啟動時指定的檔案參數。本頁範例使用 mihomo 常見欄位；其他 Clash 系列核心可能只支援其中一部分，用戶端也可能在啟動前另外產生一份執行設定。排查時，請先確認核心名稱、設定來源與最終載入路徑，再檢查特定欄位是否生效。

映射、清單與縮排

YAML 以鍵和值組成映射，例如 mode: rule；清單則以連字號逐項列出，例如 rules 中的多條規則。頂層欄位從行首開始，子欄位以空格縮排，建議統一使用兩個空格。縮排深度代表欄位的從屬關係，不是排版裝飾。若將 nameserver 與 dns 對齊，它就會從 DNS 子項變成另一個頂層鍵；即使檔案通過語法解析，也不代表核心會依預期使用它。

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

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query

proxy-groups:
  - name: 出站選擇
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,出站選擇

這是一份用來檢視結構的直連設定，不含遠端代理節點。匯入後，規則會將要求交給「出站選擇」，而該組目前只有 DIRECT。這份設定適合確認檔案能否載入、連接埠是否正在監聽，以及規則能否引用組名；不能據此判斷遠端代理是否可用。其他章節的片段預設需要合併至對應欄位，請勿直接串接多段各自包含頂層 dns 的範例。

字串與資料型別

布林值寫作 true 或 false，連接埠使用整數，位址與名稱通常是字串。密碼、以特殊符號開頭的值，以及含有「冒號加空格」的文字，建議加上引號。註解以 # 開頭；若密碼含井字號，正確加上引號可避免後續內容被當成註解。單引號字串不會處理反斜線跳脫，雙引號則會解讀部分跳脫序列，因此從其他格式複製密碼時，請勿任意增刪反斜線。

清單中的每個節點通常都是一個映射。節點的 name、type、server 等鍵必須屬於同一個清單項目。漏掉連字號可能會讓新節點併入上一項；同一個映射重複設定 name 或重複設定頂層欄位，可能遭解析器拒絕，也可能出現後值覆蓋前值的情況。請勿依賴重複鍵來覆寫設定，應使用用戶端明確提供的合併功能。

完整設定與節點集合的差異

完整設定可包含連接埠、DNS、節點、策略組與規則；代理集合檔案通常只提供 proxies 清單，規則集合則有自己的 payload 結構。三者都能使用 YAML，但不能互相替代載入位置。訂閱網址回傳合法 YAML，不代表可以直接匯入為主設定。若回傳內容是單節點 URI、Base64 文字或登入頁面，應先確認訂閱格式，而不是繼續修改縮排。

編輯前請備份原始檔案，並使用能顯示空白字元的 UTF-8 編輯器。先保留最小可載入結構，再依序加入 DNS、節點、策略組與規則，每次只修改一個區域。如此一來發生錯誤時，便能明確知道要回復哪一部分。線上 YAML 格式化工具並非必要；設定通常含有訂閱網址與認證資訊，使用本機編輯及語法檢查更適合處理這類檔案。

連接埠、模式與存取範圍

通用欄位會決定核心如何接收要求、採用哪種路由模式，以及允許哪些裝置存取。請先區分三種入口：應用程式主動向 HTTP 或 SOCKS 連接埠傳送代理要求；系統代理設定會將支援該設定的應用程式指向這些連接埠；TUN 則透過虛擬網路介面接管符合路由條件的流量。啟用監聽連接埠不會自動設定系統代理，啟用系統代理也不代表所有程式都會遵循。排查入口問題時，應確認應用程式實際使用哪種代理方式。

port、socks-port 與 mixed-port

一般桌面使用可先只設定 mixed-port，減少應用程式與連接埠的對應設定。請勿讓多個監聽欄位在同一個位址使用相同連接埠，也別忽略其他用戶端或舊核心程序可能已占用連接埠。修改連接埠後，應用程式中手動填寫的代理位址不一定會同步更新。由用戶端管理的系統代理可能會跟著變更，但仍請檢查系統設定中的主機與連接埠是否指向目前的執行個體。

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

allow-lan 與 bind-address

allow-lan: false 適用於僅供本機存取的情境。若要讓區域網路裝置使用代理，再將它設為 true，並設定適當的 bind-address。綁定 127.0.0.1 只接受本機 IPv4 回送連線；綁定 "*" 則會擴大監聽範圍。監聽範圍、作業系統防火牆、路由器隔離與用戶端認證會共同影響連線可達性，單獨切換一個布林值，無法保證手機或電視一定能連線。

區域網路裝置應填入執行核心的電腦位址，而不是自己的 127.0.0.1。電腦位址可能因 DHCP 租約而變動，可在路由器設定位址保留以減少變更。分享時，建議只允許可信任的網段存取，請勿將代理連接埠對外公開。相關操作與防火牆檢查請參閱mixed-port 與 allow-lan 區域網路分享說明。分享入口不等於管理入口，兩者應分別限制存取。

mode 與記錄層級

mode: rule 會依照 rules 順序選擇目標；global 使用全域策略選擇；direct 則採用直連模式。切換模式有助於縮小排查範圍，但全域模式下能連線，不代表規則模式一定有語法錯誤；也可能只是某條規則選到了不同的出站。規則模式下，內網要求、指定網域與未命中規則的要求可以使用不同目標，這也是需要維護規則順序的原因。

log-level 通常使用 info，排查問題時可暫時改為 debug。詳細記錄可能包含瀏覽過的網域、連線目標或訂閱資訊，不適合長期公開保存。ipv6: false 會控制核心相關的 IPv6 行為，但不會自動關閉作業系統所有 IPv6 網路功能；DNS 子項也有獨立的 ipv6 設定。理解流量入口時須一併考量這兩處設定，不能據此宣稱整台裝置的 IPv6 已遭封鎖。

TUN 的 enable、auto-route、auto-detect-interface 與 dns-hijack 都涉及權限、網卡和系統路由。設定語法相似，不代表各平台的安裝流程相同。請先依照入門步驟確認一般代理入口正常，再啟用 TUN；否則連接埠、權限與 DNS 問題同時出現，會讓故障範圍難以判斷。

DNS 與 Fake-IP

dns 是獨立的映射區域。enable 決定是否啟用內建 DNS，listen 指定監聽位址，enhanced-mode 則決定增強解析模式。DNS 啟用後，系統查詢是否真的進入核心，仍取決於系統 DNS、TUN 劫持或其他轉送設定。如果設定了監聽位址，卻沒有任何查詢送到該位址，核心就無法為這些查詢建立網域映射，也無法取代應用程式自行使用的加密 DNS。

基礎解析鏈與加密上游

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  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
  fake-ip-filter:
    - "*.lan"
    - "localhost"
  nameserver-policy:
    "+.lan": 192.168.1.1

範例中的 192.168.1.1 假設是能解析本機名稱的路由器，實際網路環境不同時請替換成適用的位址。nameserver 是一般上游清單，支援的位址格式依核心而異；範例使用 HTTPS DNS。上游位址本身若包含主機名稱，還需要先解析該主機名稱；default-nameserver 常用於這類引導解析。請勿讓引導解析又依賴尚未建立的同一條代理鏈，否則會形成啟動階段的循環依賴。

nameserver-policy 可依網域指定解析器，適合將區域網路網域交給本機 DNS。它控制的是查詢要交給哪個解析器，不等同於 rules 中的連線出站選擇。fallback 與 fallback-filter 可能參與結果選擇，但並非單純「第一台伺服器失敗後就查第二台」。若沒有明確的分流需求，先維護一條容易理解的解析鏈，比同時加入多個公共上游更容易驗證。

Fake-IP 與 redir-host 的差異

使用 fake-ip 模式時，核心可向應用程式回傳保留位址池中的合成位址，再依映射還原網域並選擇出站。這些位址並非目標網站的真實位址，因此命令列顯示 198.18 開頭的結果，不一定代表解析錯誤。redir-host 則以實際解析結果為主。兩種模式都需要正確的流量入口與網域資訊；應依應用程式相容性、DNS 路徑與透明代理方式選擇。

fake-ip-filter 用於排除不適合回傳合成位址的網域，例如部分本機名稱或有特殊驗證機制的服務。它不會將整個應用程式的流量改為直連，也不會自動修改路由規則。遇到相容性問題時，請先以一個明確網域進行最小範圍排除，再比較結果；不要把所有常見後綴都加入篩選清單。排除範圍過大會讓不同流量採用不同解析路徑，增加後續維護難度。

節點解析與規則解析

代理伺服器的網域必須在連線代理前解析。mihomo 的 proxy-server-nameserver 可用來指定這類查詢的上游；若要依規則處理 DNS 連線，還會涉及 respect-rules。設定這些項目時，必須避免代理伺服器網域的解析再次依賴該代理本身。先確認節點位址能透過一般直連上游解析，再逐步加入 DNS 出站規則，比直接複製複雜的分流片段更可靠。

IP 類規則可能需要先解析網域，才能判斷目標位址是否落在特定網段。規則中的 no-resolve 可避免該 IP 規則額外觸發解析，但不會阻止應用程式已發出的 DNS 查詢。排查 DNS 洩漏時，須分別檢查系統解析、應用程式內建 DoH、核心上游及代理端解析；只查看瀏覽器顯示的一個 DNS 位址，無法代表裝置上的所有查詢都走同一條路徑。

驗證時，先查詢一般網域，再查詢本機網域，最後測試對應服務的連線。若一般網域可用、本機名稱卻失敗，優先檢查本機解析策略與篩選項目；若所有查詢都逾時，則檢查監聽位址、連接埠、防火牆與上游可連線性。DNS 回應與應用程式連線成功是兩個階段，解析失敗時不應先修改節點協定參數。

代理節點欄位

proxies 是節點清單，每個項目描述一個可供策略組引用的出站。常見共用欄位包含 name、type、server 與 port；認證與傳輸欄位則依協定而異。節點名稱是設定中的引用識別，不只是顯示用備註。修改名稱後，也要更新策略組中的同名引用。名稱應保持唯一，避免不同節點使用相同名稱，導致難以判斷實際選取的節點。

基本欄位與協定專用欄位

type 決定核心如何依協定解讀其餘參數。例如 Shadowsocks 需要 cipher 與 password，Trojan 使用密碼並涉及 TLS，VMess 與 VLESS 則使用各自的識別資訊和傳輸參數。只把 type 從一種協定改成另一種，並不能完成轉換。伺服器協定、認證方式、傳輸層與 TLS 設定都必須符合伺服器實際設定；缺少的參數請向服務提供者確認。

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

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

此處使用文件保留位址與範例網域，僅展示欄位結構，並非可連線的服務。實際使用時，請完整替換伺服器位址、認證資訊及 TLS 主機名稱。server 可以是 IP 或網域；port 是伺服器監聽的連接埠，與本機的 mixed-port 不同。伺服器若使用網域，連線前還會解析節點網域；若使用 IP，也可能需要另外設定 TLS 主機名稱。

TLS、SNI 與憑證驗證

Trojan 通常使用 sni 指定 TLS 交握時的伺服器名稱；其他協定可能使用 servername 等欄位，請依協定定義填寫。TLS 主機名稱須符合伺服器憑證及部署方式，不能任意填入網頁網域。skip-cert-verify: false 代表維持憑證驗證。若憑證發生錯誤，請先檢查系統時間、主機名稱與憑證鏈，不應將略過驗證當作通用修復方式。

WebSocket 要求路徑、Host 要求標頭與 gRPC 服務名稱屬於不同的傳輸設定，並非同一個欄位。伺服器要求使用 WebSocket 時，用戶端也須設定相應的 network 與 ws-opts；路徑中的大小寫及斜線可能影響路由。將既有 URI 轉成 YAML 後，請逐項核對這些細節。連結中的編碼字元必須正確解碼；密碼或路徑解碼錯誤，可能造成「設定載入成功，但交握失敗」。

UDP 與鏈路能力

udp: true 代表在支援此欄位的協定中啟用相應的 UDP 功能，但不保證整條傳輸路徑都能傳送 UDP。應用程式入口、代理協定、伺服器部署、防火牆與電信網路都可能形成限制。若網頁 TCP 要求正常、即時通訊卻失敗，請先確認應用程式是否確實透過支援 UDP 的入口，再檢查節點設定。HTTP 探測成功，不能證明 DNS、QUIC 或遊戲流量一定正常。

部分協定還會用到 ALPN、用戶端指紋、Reality 或其他專用參數。欄位是否可用取決於核心實作；舊版用戶端即使接受 YAML，也可能不支援對應協定。遇到未知欄位或不支援的類型時，請先確認核心能力，再決定是否更換用戶端；可前往下載頁選擇 Clash Plus 或其他適合該平台的用戶端。請勿為了讓設定通過而刪除不熟悉的欄位，這可能會改變伺服器要求的認證或傳輸方式。

手動維護節點適合少量固定出站；節點經常變動時，建議使用代理集合集中更新，再由策略組引用。請勿逐次手動修改訂閱產生的節點名稱，因為下次更新可能會還原。若問題發生在格式轉換後，可參考YAML 訂閱與節點連結格式說明，檢查認證、傳輸與 TLS 參數是否完整保留。

策略組與代理集合

proxy-groups 定義出站選擇邏輯，proxy-providers 則定義節點集合來源。兩者用途不同：集合提供候選節點，策略組決定如何從候選中選擇。規則通常引用穩定的組名，而不是經常變動的節點名稱。如此一來，只要組名與集合引用仍有效，更新節點時就不必逐條修改規則。策略組也可引用其他組，但應避免自我引用或互相循環引用。

select、url-test 與 fallback

select 由使用者或管理介面選擇成員，適合明確控制出站；url-test 依指定網址的探測結果自動選擇；fallback 通常依成員順序選用可用項目。load-balance 用於支援的負載平衡策略，不能理解為將單一連線拆成多條線路來疊加頻寬。不同類型解決的問題不同，不應只因為想要「自動」就把所有分流組都改成自動測試。

proxy-groups:
  - name: 出站選擇
    type: select
    proxies:
      - 自動選擇
      - 故障切換
      - DIRECT

  - name: 自動選擇
    type: url-test
    use:
      - 自有節點
    url: https://cp.cloudflare.com/generate_204
    interval: 300
    tolerance: 50

  - name: 故障切換
    type: fallback
    use:
      - 自有節點
    url: https://cp.cloudflare.com/generate_204
    interval: 300

proxy-providers:
  自有節點:
    type: file
    path: ./providers/nodes.yaml
    health-check:
      enable: true
      url: https://cp.cloudflare.com/generate_204
      interval: 300

範例假設工作目錄下有 providers/nodes.yaml，其內容為包含 proxies 清單的節點集合。use 引用的是 provider 名稱「自有節點」，不是檔名或特定節點。proxies 清單則直接引用既有節點、其他組或內建出站。兩種引用方式可以搭配使用，但須確認候選集合確實有內容，否則自動選擇組可能沒有可用成員。

探測參數的實際作用

url 決定健康檢查要求的目標，interval 通常以秒為單位設定探測間隔，tolerance 則在相應的自動選擇邏輯中用來減少因微小差異而頻繁切換。探測結果反映的是前往測試目標的要求過程，不代表所有網站、長連線或大型檔案傳輸的表現。目標網站封鎖要求、TLS 交握異常或 DNS 故障，都可能導致探測失敗，即使代理伺服器連接埠仍可連線。

provider 健康檢查與策略組測試可能分別存在。設定前請先確認哪些測試由集合負責、哪些由策略組負責，避免對同一批節點進行不必要的高頻檢查。檢查間隔不是愈短愈好，尤其在行動裝置上還會增加喚醒與網路要求。既有連線通常不會因策略組切換而立即改用新節點，因此切換後應建立新連線測試，不要只觀察先前持續下載的工作。

集合更新、篩選與名稱穩定性

HTTP 類型的 proxy-providers 會以 url、path 與 interval 描述遠端來源、本機快取與更新週期。下載內容必須是核心接受的集合格式，不能是任意網頁或完整用戶端設定。遠端連結若含有憑證，請保存在本機設定中，不要貼到公開問題回報。訂閱更新錯誤可參考訂閱更新失敗排查，先判斷是要求失敗還是內容解析失敗。

策略組的 filter 可依名稱篩選候選項目，使用時應將比對條件視為正規表示式。名稱慣例一旦改變，篩選結果可能變成空集合；因此更新訂閱後，除了檢查節點清單，也要確認各組實際包含的成員。地區名稱、特殊符號與大小寫都會影響比對。先用簡單條件確認能選中目標，再逐步縮小範圍，比一次寫入複雜運算式更容易維護。

profile.store-selected 可保存策略組的選擇，profile.store-fake-ip 可保存相關映射狀態。是否需要持久保存，取決於使用方式與用戶端管理邏輯。修改組成員後應重新確認目前選擇，避免保存的舊選項、篩選結果與實際執行設定不一致。

規則與規則集合

rules 是有順序的清單。核心會由上而下尋找符合條件的規則，命中後便使用該規則指定的出站目標。規則不會依「看起來較精確」自動排序，也不會讓後面的網域規則優先執行。通常先放明確的本機或業務例外，再放範圍較廣的網域、位址與規則集合，最後用 MATCH 作為兜底。順序本身就是設定邏輯，編輯規則時也要一併檢查前後條件。

網域、位址與兜底語法

rules:
  - DOMAIN,intranet.example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,出站選擇
  - DOMAIN-KEYWORD,example,出站選擇
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - RULE-SET,本地域名,DIRECT
  - MATCH,出站選擇

DOMAIN 比對完整網域，適合指定單一主機；DOMAIN-SUFFIX 比對指定網域及其子網域；DOMAIN-KEYWORD 依關鍵字比對，涵蓋範圍較廣。關鍵字規則寫得太短，可能連不相關的網站也一起命中。IP-CIDR 與 IP-CIDR6 分別比對 IPv4 與 IPv6 網段。範例中的內網範圍並不完整，僅用來說明語法；請依實際網路補充，不要將這段視為完整的私有位址清單。

規則末尾的出站可以是節點名稱、策略組名稱，或 DIRECT、REJECT 等內建目標。名稱必須完全符合定義，包括空格與標點。MATCH 不需要額外條件，因此應放在兜底位置；若放在清單開頭，後續多數規則便沒有機會執行。業務規則未命中時，請先確認前面是否已有範圍較廣的規則攔截，不要直接再加一條相似規則。

rule-providers 宣告與檔案格式

rule-providers 用來重複使用一組比對條件。type 表示檔案或 HTTP 來源，behavior 表示內容語意，format 表示序列化格式。domain 集合存放網域比對項目，ipcidr 集合存放位址範圍，classical 集合則可包含相應的傳統規則條件。請勿將代理節點集合放入規則集合目錄；雖然都採用 YAML，根欄位與各項內容並不相同。

rule-providers:
  本地域名:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domain.yaml

# ./rules/local-domain.yaml 的內容：
# payload:
#   - "+.lan"
#   - "intranet.example.com"

上述檔案中的 payload 是獨立檔案的內容，不要把註解誤認為已建立該檔案。主設定透過 RULE-SET,本地域名,DIRECT 指定這組條件的目標。使用 classical 格式時，集合項目通常描述條件，不應照搬主設定規則，機械式地加上出站名稱。遠端集合還涉及下載與快取；若首次啟動時無法取得且沒有本機快取，就必須先排除資源無法連線的問題。

解析時機、程序與平台差異

某些 IP 條件為了比對網域要求，可能會觸發解析；相應規則若帶有 no-resolve，則不會為了比對而主動解析網域。這個選項適合已有目標 IP 的流量，但也可能讓原本預期依賴解析結果的規則無法命中。網域規則需要核心取得網域資訊；若流量只有目標 IP，也沒有可用的 DNS 映射或嗅探結果，就不能假設網域條件仍會生效。

PROCESS-NAME 等程序規則依賴作業系統提供的資訊、核心權限與流量入口。桌面應用程式可用的程序條件，不一定適用於路由器後方的另一台裝置。GEOIP、GEOSITE 也依賴相應的資料資源與核心支援，資料庫內容變更還會影響比對結果。跨平台移轉時，請先檢查這些外部依賴，不要只比較規則文字是否相同。

規則檔案應依用途分區，並加上簡短註解。測試例外規則時，先將明確的測試網域放在較前方，建立新連線確認命中，再調整至長期使用的位置。不要持續把新規則插在最上方當成永久修正，否則後續維護者難以判斷優先順序，也更容易讓範圍過廣的規則掩蓋既有分流邏輯。

訂閱、覆寫與合併

用戶端中的「訂閱設定」不一定就是核心最後讀取的檔案。常見流程包括下載遠端文件、儲存訂閱副本、套用本機覆寫或腳本、補上介面管理的連接埠與 TUN 設定，最後產生執行設定。不同用戶端的階段名稱與執行順序可能不同。排查「檔案已修改，但設定沒有變更」時，請先找到執行設定或設定預覽功能，比對最終欄位，而不是反覆編輯下載快取。

區分來源檔案、持久設定與執行結果

來源檔案用來保留訂閱提供的內容；本機覆寫用來設定裝置專屬需求；執行設定則是兩者與用戶端設定組合後的結果。這三個層次可能各自包含相同的 mixed-port、dns 或 tun。介面開關也可能有較高優先權。不要依檔名猜測優先順序，應查看用戶端說明或進行單欄位測試：只修改一個連接埠或記錄層級，重新產生設定後觀察結果。

Clash Plus、Clash Verge Rev、FlClash 等用戶端的設定管理介面並不完全相同，匯入設定、擴充與合併的入口須依實際使用的用戶端確認。更換用戶端時，不要把某款用戶端專用的擴充腳本當成通用 mihomo 欄位。核心讀取的是最終設定，用戶端則負責產生該設定。用戶端選擇與平台支援請參考選型指南，首次操作仍請依照快速入門完成。

映射合併與清單取代

映射可以逐鍵覆寫，清單則可能整段取代、移至前方或附加在後方；具體規則取決於合併工具。以 dns 為例，遞迴合併可能只取代 nameserver，並保留其他子鍵；淺層取代則可能讓整個 DNS 區域只剩下新內容。對 rules 使用清單取代，可能會遺失訂閱中的所有分流規則。不能只憑「合併」兩個字，就認定原有設定一定會保留。

# 適用於支援 YAML 覆寫的用戶端；
# 是否採用遞迴合併，請確認該用戶端的規則。
log-level: info

profile:
  store-selected: true
  store-fake-ip: true

dns:
  enable: true
  nameserver:
    - https://dns.alidns.com/dns-query

套用這段覆寫後，請確認原有的 dns.listen、enhanced-mode、篩選清單與解析策略是否仍然存在。若結果不符預期，應調整合併方式，而不是繼續堆疊重複欄位。也要檢查規則前置或後置的位置：在既有 MATCH 後追加一般規則，通常無法達到預期的分流效果；將範圍過廣的規則放在前面，又可能攔截原有的業務例外。

訂閱更新與本機修改保護

直接修改下載後的訂閱檔案，更新時可能會被遠端內容覆蓋。要長期保留的本機 DNS、區域網路規則與連接埠設定，應放在用戶端支援的本機持久設定層。手動維護的節點集合與規則集合也應使用獨立路徑，不要與訂閱快取共用同一個檔案。若多個 HTTP provider 使用相同的快取路徑，內容可能互相覆蓋，造成節點突然消失或解析出錯誤結構。

訂閱格式轉換不代表所有欄位都能完整保留。單節點 URI 通常無法表達完整的 DNS、規則與策略組；將完整 YAML 轉為節點連結時，這些頂層設定可能會遺失。轉換後應先比對協定、認證與傳輸設定，再檢查策略組和規則是否由轉換工具重新產生。處理私人訂閱時，請勿將完整連結交給來源不明的線上轉換服務，優先使用可信任的本機工具或服務提供者支援的格式。

可復原的更新流程

更新前請備份目前可用的設定與本機擴充內容，並記下目前選取的設定名稱。更新後先執行語法檢查，再確認策略組成員與規則目標，最後建立新連線測試。若下載成功卻載入失敗，請比對回傳內容是否變成網頁、錯誤訊息或其他訂閱格式；若載入成功但行為改變，應比對執行設定，而不只查看原始訂閱。逾時、連結過期與自動更新間隔等問題，可繼續參考訂閱更新排查文章。

需要分享設定差異時，只保留相關欄位與已隱去敏感資訊的引用關係。不要為了說明一個 DNS 子鍵就上傳整份執行設定，因為其中可能包含節點密碼、管理認證與遠端訂閱憑證。能重現問題的最小片段，比含有大量無關規則的完整檔案更容易得到準確判斷。

驗證、記錄與排查流程

設定驗證應從靜態結構逐步進到實際連線，不要一開始就同時切換模式、節點與 DNS。先確認核心接受檔案，再確認要求進入正確連接埠，接著觀察規則命中與節點連線。每一步只排除一個層面的問題，並記錄輸入、結果與修改內容。完整設定中有多個可用節點，不代表目前策略組選取的節點一定可用；同樣地，用戶端介面顯示正在執行，也不能取代實際要求測試。

先檢查檔案，再載入執行

直接執行 mihomo 的使用者可使用設定測試參數。命令中的目錄應替換成實際工作目錄；相對 provider 路徑與快取路徑會受工作目錄影響。GUI 使用者請優先使用用戶端內建的檢查、預覽或記錄功能，不要另外啟動第二個執行個體，造成相同連接埠被占用。通過設定檢查後，還要查看啟動記錄是否有監聽失敗或資源載入錯誤，這些問題不一定能在靜態檢查階段發現。

# 請在設定檔與資源所在目錄執行
mihomo -t -d . -f ./config.yaml

# 透過本機 HTTP 代理入口送出要求
curl -I --proxy http://127.0.0.1:7890 https://example.com

# 使用 SOCKS，並由代理端解析網域
curl -I --proxy socks5h://127.0.0.1:7890 https://example.com

兩種 curl 要求的 DNS 路徑可能不同，不能視為完全相同的測試。socks5h 會讓代理端解析主機名稱；一般的 socks5 通常由本機先行解析。在 Windows 上，若終端機中的 curl 被對應成其他命令，請明確呼叫實際的 curl 程式。出現 HTTP 錯誤狀態，不一定表示代理無法連線；應區分是網站拒絕要求、代理認證失敗，還是底層連線失敗。

依錯誤階段縮小排查範圍

錯誤行號有時指向解析器停止的位置，而不一定是最早出錯的位置。檢查該行時，也要查看前一行是否漏了引號或冒號。代理名稱不存在通常是引用問題，不需要先調整網路。遇到連線逾時時，應先確認逾時的是訂閱伺服器、節點伺服器還是目標網站，再分別沿著下載鏈、代理鏈與網站連線排查。

記錄與最小重現

短暫啟用 debug 後，只重現一個目標要求，記下時間、目標、命中規則與最終出站，再恢復一般記錄層級。如果同時有 TUN、系統代理與應用程式手動代理三種入口，請先保留其中一種明確入口進行比對。瀏覽器連線池、背景服務與 DNS 快取可能讓舊連線持續存在，因此每次重要修改後，應使用新的要求程序或重新啟動測試應用程式，避免觀察到舊狀態。

最小重現可保留一個已確認可用的節點、一個手動選擇的策略組、一條指向測試網域的規則，以及末尾的兜底規則。若最小設定可用，再依序恢復 DNS 策略、規則集合、自動選擇與本機覆寫。不要只因為刪除所有規則後問題消失，就認定規則本身有問題；刪除過程也可能改變 DNS 解析時機與預設出站。保留每一步的設定差異，才能確認是哪項變更影響結果。

常見邊界問題

完成排查後，請移除臨時測試規則、恢復適當的記錄層級，並確認區域網路存取範圍沒有因排查而擴大。將穩定的修改移回本機持久覆寫層，再測試一次訂閱更新與重新載入。如此不僅能驗證目前的連線，也能確認下次更新後設定仍符合預期。