Clash 進階設定

策略組類型與實際應用

策略組負責決定「符合這類連線時，使用哪個出口」。規則用來辨識流量，策略組用來選擇目標，節點則負責建立實際連線，三者用途不同。規則命中正確但無法連線，問題可能出在組內選項或節點；節點連得上但流量走錯出口，則應檢查規則順序與組名引用。先在連線頁面記下命中的規則、策略鏈與最終出口，才能判斷該調整哪一層。

手動選擇、自動測速與故障切換

select 可手動指定成員，適合需要固定出口的服務。成員可以是節點，也可以是其他策略組。建議保留手動選擇作為最外層入口，並將自動組設為其中一個選項。自動測速結果若與實際使用體驗不符，就能暫時固定出口，不必重新編輯所有規則。選擇狀態可能由用戶端或核心快取；重新載入設定後，請確認實際選取的項目。

url-test 會定期連線至測試網址，並依測試結果選擇成員；tolerance 可減少因細微差異而頻繁切換。測試反映的是連線至該網址的狀況，不代表所有網站、下載任務或即時通話的表現。fallback 著重依成員順序選擇可用出口，適合主備配置；第一個可用成員恢復後，可能會再次被選中，因此不應將它視為會永久固定目前節點的策略組。

load-balance 會將不同連線分配給不同成員，常見策略包括 consistent-hashing 與 round-robin。它不會把單一連線拆分至多個節點以累加頻寬。登入工作階段、付款驗證與長連線服務等業務，可能對出口變動較敏感，通常較適合固定選擇。即使採用一致性雜湊，成員新增或移除仍會改變分配結果，因此不能保證出口絕對穩定。

先建立清楚易懂的策略鏈

以下最小範例只使用內建直連目標，方便理解引用關係。實際使用時，請將現有節點或自動組加入「手動出口」的成員清單。業務組引用出口組，規則再引用業務組，名稱必須完全一致。名稱含空格或特殊字元時，建議加上引號。避免業務組與出口組互相引用；循環相依會導致設定檢查失敗，或讓介面顯示的選擇鏈失去意義。

proxy-groups:
  - name: 手動出口
    type: select
    proxies:
      - DIRECT
  - name: 日常瀏覽
    type: select
    proxies:
      - 手動出口
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,日常瀏覽
  - MATCH,手動出口

節點來自 proxy-providers 時，請在組內透過 use 引用提供者名稱，而不是將訂閱網址填入 proxies。自動組通常還需要設定 url 與 interval；例如可使用 https://www.gstatic.com/generate_204 作為測試網址，間隔設為 300 秒。這個網址僅供連線探測；若不適用於目前網路環境，請更換網址，不要只因一次探測結果就刪除整份訂閱。

切換後的驗證與排錯

修改組內選擇後，請先建立新的連線，再查看連線詳細資料。既有連線通常不會因策略組切換而自動轉移；瀏覽器重用連線時，也可能繼續使用舊出口。驗證時可關閉相關連線，或重新啟動測試用的應用程式。關閉連線會中斷正在進行的工作，請先確認下載、會議與遠端工作階段均可結束。不要因舊連線未變化，就誤以為設定重新載入失敗。

若自動組一直沒有可選成員，請依序檢查提供者是否載入成功、篩選條件是否過嚴、成員名稱是否相符，以及健康檢查是否執行。若成員存在卻頻繁切換，則檢查探測逾時、測試網址是否可連線及容差設定。盡量減少重複探測：多個自動組同時高頻測試同一批節點，會增加連線數與耗電量，尤其不適合在行動裝置上長時間執行。

以訂閱管理規則集

規則集可將「辨識哪些流量」的內容從主要設定中分離。主要設定保留策略順序與目標組，提供者檔案則維護網域或網段集合。更新某個業務分類時，就不必一併修改所有節點與 DNS 參數。採用訂閱管理也會帶來新依賴：規則來源、下載路徑、本機快取與檔案格式必須彼此相符。規則集下載成功不代表已參與比對；還需要在 rules 中透過 RULE-SET 引用。

選擇 behavior 與檔案格式

behavior: domain 適用於網域集合，ipcidr 適用於網段集合，classical 則適用於包含規則類型的完整項目。不能只根據副檔名判斷行為類型。同樣是 YAML，網域集合內容可能是 +.example.com，而 classical 項目可能是 DOMAIN-SUFFIX,example.com。混用兩者可能導致解析失敗或比對結果不符；匯入前請先閱讀來源對格式的說明。

format 決定檔案的讀取方式，可依來源選擇 yaml、text 或相應的二進位規則格式。YAML 規則集通常在 payload 下列出項目；文字格式則以逐行方式儲存。二進位規則格式有行為類型限制，不能只把任意 classical 檔案改副檔名，就當成可用格式。需要轉換時，請使用核心支援的轉換工具，並保留原始資料，以便比對轉換前後的語意。

先用本機規則集驗證流程

先定義檔案型提供者，避免把遠端下載問題與規則比對問題混為一談。範例中的 ./rules/local-sites.yaml 是相對於設定工作目錄的路徑，不一定等於介面匯入檔案的位置。桌面用戶端可能會在獨立的核心目錄產生執行設定；請先確認實際工作目錄，並在該目錄建立規則檔案。若目錄不存在或檔案權限不足，先處理讀取錯誤，再檢查規則內容。

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

rules:
  - RULE-SET,local-sites,DIRECT
  - MATCH,手動出口

在對應的 local-sites.yaml 中加入以下內容。+.example.com 是 mihomo 網域集合常見的後綴比對寫法，可涵蓋該網域及其子網域。請留意，這與 rules 中以逗號分隔的完整規則不是相同結構。儲存後重新載入，瀏覽該網域並查看連線規則；本節的「手動出口」沿用上一章定義，若要單獨測試，請先建立同名策略組。

payload:
  - '+.example.com'
  - '+.example.org'

本機比對驗證成功後，再改用 type: http，加入有效的 url 與 interval，並保留唯一的快取 path。更新間隔的單位是秒，請依來源更新頻率設定，不必為了追求「即時」而頻繁請求。若規則來源必須經由代理下載，可依目前核心的支援情況指定下載策略；同時確認該策略不依賴尚未載入的同一份規則，以免初始化時互相等待。

規則順序比分類數量更重要

連線通常會依規則由上而下比對，第一個符合的項目會決定所用策略。請將少數明確的例外放在前面，業務分類放在中間，並將兜底的 MATCH 放在最後。範圍過大的網段或過於寬泛的網域集合若出現得太早，就會攔截後面的精細規則。兩個規則集內容重疊不一定有問題，但必須明確設定重疊時的優先順序；否則同一網域可能因順序調整而改變出口，看起來就像節點不穩定。

IP 類規則可能需要解析網域以取得目標 IP；適用的項目可使用 no-resolve，避免為比對而主動解析，但如果連線只有網域、尚無目標 IP，就可能無法符合該規則。這不是能提升所有規則效能的通用開關。請先確認分類依據是網域還是網段，再選擇行為類型；不要把網域、IP 與程序規則全塞進難以追蹤的同一個集合。

更新失敗與快取範圍

遠端更新失敗時，請檢查取得網址是否仍有效、回應內容是否真的是規則檔案、下載連線是否遭現有規則封鎖，以及本機快取是否可寫入。在瀏覽器中開啟網址並看到登入頁面，不代表核心能取得規則資料。舊快取可能讓既有分類繼續運作，也可能掩蓋來源已失效的問題；請查看提供者更新時間與記錄，不要只根據網頁能開啟就判斷更新成功。

DNS 設定最佳化

DNS 設定需要釐清三件事：由誰接收應用程式的查詢、由誰解析目標網域，以及連線到解析器時會走哪條路徑。用戶端啟用 DNS 功能，不代表所有應用程式都使用這個解析入口。瀏覽器內建的加密 DNS、系統快取、區域網路解析器與 TUN 接管範圍，都會影響實際流程。最佳化時應先觀察查詢來源，而不是一次填入大量解析器，期待數量自然帶來可靠性。

區分一般網域解析與節點位址解析

nameserver 用於一般目標解析；default-nameserver 主要用於引導解析解析器網域，不是所有查詢失敗時的通用備用伺服器。代理節點伺服器若使用網域名稱，其解析發生在建立代理連線之前，可透過 proxy-server-nameserver 個別設定。否則，節點位址解析若依賴尚未建立的代理連線，就可能形成循環：必須先連上代理才能查詢，但又必須完成查詢才能連上代理。

nameserver-policy 可為特定網域指定解析器，適用於內部網域或有明確解析需求的服務。區域網路名稱應交由了解該網路的解析服務處理，而非一律使用公共解析器。以下範例用來展示設定結構，位址僅代表一種參數組合，實際設定請依網路連線狀況選擇。監聽位址限定為本機；若只是測試 DNS，不必先將監聽連接埠開放給其他裝置。

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://cloudflare-dns.com/dns-query
  proxy-server-nameserver:
    - https://cloudflare-dns.com/dns-query
  nameserver-policy:
    '+.home.arpa':
      - system

home.arpa 是供家庭網路名稱使用的特殊網域；範例將它交由系統解析路徑處理，但系統解析器仍須確實支援該名稱。不要因此認定所有區域網路都使用相同網域。企業內網可能需要指定內部 DNS 位址，修改前請記錄原有系統設定。若裝置同時連線至 VPN 與本機網路，也要確認通往內部解析器的路由沒有被代理規則或另一條 VPN 隧道攔截。

了解加密 DNS 的傳輸路徑

DoH 與 DoT 保護的是傳送至解析器的查詢，不會決定業務連線是否經由代理。使用加密 DNS 仍需要可連線的解析器、正確的系統時間與有效的憑證鏈。啟用 respect-rules 後，解析器連線會依規則選擇路徑，因此也要妥善設定節點網域解析，避免形成循環相依。這個參數並非越早啟用越好；請先確認基本解析正常，再檢查解析器連線命中的規則。

fallback 與 fallback-filter 可依網域或回傳位址協助選擇解析結果，但也會增加查詢量與相依項目。不同解析器對同一網域回傳不同位址，可能是 CDN 調度、快取時間或連線位置所致；不能只因結果「不一樣」就判定有異常。請先記錄失敗網域、解析結果與實際連線位址，再決定是否需要設定解析策略，不要將所有差異都交由備用解析器處理。

以單一網域測試取代全面重設

在具備 dig 的系統上，可執行以下命令直接查詢本機監聽連接埠。Fake-IP 模式下收到映射位址是預期情況；這項測試只能確認本機 DNS 能回應，無法單獨證明實際服務可連線。接著請使用應用程式連線，檢查連線是否保留網域名稱、規則是否正確，以及出口是否可用。若沒有收到回應，請檢查監聽狀態、設定是否生效，以及連接埠是否被其他程序使用。

dig @127.0.0.1 -p 1053 example.com A

若只有瀏覽器無法連線，但命令查詢正常，請先檢查瀏覽器的安全 DNS、擴充功能與快取；若所有應用程式都無法連線，再檢查系統 DNS 與接管設定。切換增強模式後，舊的解析快取可能保留不適用於新路徑的位址；請關閉相關應用程式的連線，並依系統方式清除快取。若出現 HTTPS 憑證錯誤，請勿關閉憑證驗證來掩蓋問題，可參考憑證錯誤與代理的關係解析，區分時間、憑證鏈與網路路徑問題。

TUN 與 Fake-IP

TUN 是流量接管入口，Fake-IP 則是 DNS 與連線的關聯方式，兩者可以搭配使用，但不是同一個開關。系統代理主要影響遵循代理設定的應用程式；TUN 透過虛擬網路介面與路由，讓更多 IP 流量進入核心。Fake-IP 會建立網域與映射位址之間的關聯，連線進入核心後再依網域處理。理解這兩個層次，才能判斷「啟用 TUN 後仍有應用程式未被接管」或「收到映射位址卻無法存取」的原因。

權限、虛擬介面與預設路由

啟用 TUN 前，請先確認 Clash 用戶端具備建立介面與調整路由的權限。桌面系統通常需要管理員授權、服務模式或特權輔助元件；行動系統則透過 VPN 授權建立接管介面。介面顯示已啟用，只代表用戶端嘗試啟動；請繼續查看核心記錄中的介面與路由狀態。若多個 VPN、虛擬機網路或安全軟體同時修改路由，單靠反覆重新啟動用戶端，無法判斷衝突來源。

以下是常見的起始設定片段。auto-route 會自動設定接管路由，auto-detect-interface 會嘗試選擇出口介面，dns-hijack 則會將指定 DNS 流量交給核心 DNS 模組處理。stack: mixed 是否支援及其實際行為，應以執行中的核心為準；若用戶端會產生自己的 TUN 設定，請在最終執行檔案中確認參數值，而不只是檢查原始訂閱檔案。

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

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - '+.home.arpa'

DNS 劫持只會處理此處列出的傳統 DNS 連接埠流量，不會自動解密應用程式內建的 DoH，也不代表會接管所有多點傳送名稱探索協定。區域網路探索、印表機與裝置控制可能使用獨立協定，需搭配系統路由進行觀察。行動裝置的 VPN 實作與桌面 TUN 欄位也不完全相同；部分開關由用戶端接管處理，不能假設桌面 YAML 的每個欄位都會出現在手機介面中。

Fake-IP 映射與例外網域

映射位址不是網站的真實伺服器位址，不應複製到瀏覽器中當作永久存取網址。應用程式需透過網域查詢取得映射位址，再由核心依照映射關聯建立實際連線。若查詢由核心處理，但連線繞過核心，應用程式就可能把映射位址當成真實目的地，導致連線逾時。因此，使用 Fake-IP 模式時，必須確保相關查詢與業務連線走相同路徑；尤其是只接管部分應用程式時更要留意。

fake-ip-filter 可讓特定名稱依篩選模式回傳真實位址，常用於需要實際位址的本機服務或相容性例外。範例以預設的黑名單篩選方式為前提；若使用其他篩選模式，請重新確認清單代表的意義。篩選不是「讓這些網域直連」的規則，只會改變 DNS 回應方式，最終出口仍由 rules 決定。新增例外後，也要檢查快取與既有連線，否則應用程式可能繼續使用舊映射。

映射範圍通常使用特殊用途位址區段，不可任意改成家庭網路正在使用的私有網段。若與既有路由、另一個 VPN 或測試網路衝突，必須一併調整 DNS 映射範圍與接管路徑，而不只是更換一個位址。也要完整考量 IPv6：應用程式可能優先使用 AAAA 結果，若只驗證 IPv4，便可能忽略 IPv6 路徑未被接管的情況。是否啟用 IPv6，應依網路環境與用戶端支援狀況決定。

平台差異與復原順序

排錯時先關閉其他 VPN，只保留一個接管入口，再確認核心是否成功建立介面。接著檢查 DNS 回應，最後建立新連線並確認規則命中。若只有特定應用程式出問題，請檢查應用程式略過清單、協定類型與內建解析功能；若全系統都無法連線，優先檢查路由與 DNS 循環。完整的節點逾時排查方式，請參考從訂閱到 DNS 的逐項排錯順序，不要一次刪除所有設定。

網域嗅探

網域嗅探會從連線初期資料補充目標網域，協助只有 IP 資訊的連線符合網域規則。例如，應用程式自行解析後直接連線至位址，核心可能沒有對應的 DNS 映射；嗅探可在協定允許的範圍內讀取 HTTP Host、TLS 握手中的伺服器名稱，或支援的 QUIC 握手資訊。它補充的是可觀察到的協定中繼資料，不會讀取所有應用程式內容，也不是能解決各種連線故障的通用工具。

何時需要補充網域資訊

如果連線詳細資料已顯示正確網域，且規則命中符合預期，通常不必擴大嗅探範圍。較適合啟用的情況是：同一項服務經常只顯示 IP，導致網域分類失效，而目標協定本身具有可觀察的名稱。請先挑選一項具體服務，比較啟用前後的連線詳細資料，確認是否真的補上網域，再考慮擴大涵蓋範圍。不要只因記錄中出現嗅探動作，就認定出口已按預期變更。

以下範例限定常見的 HTTP 與 TLS 連接埠，並保留本機名稱略過清單。force-dns-mapping 與 parse-pure-ip 會擴大嘗試範圍，適用於已確認有映射缺漏或純 IP 連線的情況。初次排錯時可先不加這兩個參數，觀察預設範圍是否足夠；同時修改接管、解析與嗅探設定，會讓驗證結果難以歸因。

sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
      override-destination: false
    TLS:
      ports:
        - 443
        - 8443
  skip-domain:
    - '+.home.arpa'
    - '*.lan'

補充網域與覆寫目標的差異

嗅探取得網域後，核心可以用它輔助規則比對；是否以該網域覆寫連線目標，則由相關設定控制。override-destination 會改變目標處理方式，後續解析與連線可能不再沿用應用程式原先選定的 IP。對 CDN、內網映射或刻意指定位址的服務而言，這項變更未必合適。範例將 HTTP 的覆寫設為關閉，是為了先觀察分類結果，而非立即更改所有連線的目標位址。

若應用程式連線至某個 IP，但握手中的名稱指向另一項服務，應先確認這是否屬於正常的共用主機或特殊網路設計，再決定是否覆寫。不能只因嗅探結果「看起來像網域」，就認定它適合作為新的連線目標。若原有服務需要保留特定位址，可限定連接埠、加入略過網域，或針對該情境關閉覆寫；修改後應同時比對命中規則與最終連線位址，而不只是確認網頁能否開啟。

加密協定的可觀察範圍

TLS 伺服器名稱並非在所有情況下都能被觀察。採用加密用戶端握手資訊的連線、沒有名稱的握手，以及非標準協定，都可能讓嗅探無法取得有效網域。QUIC 也會受到核心支援、握手格式與接管路徑影響。在嗅探設定中加入 QUIC，只代表嘗試辨識相關流量；不表示會自動將 UDP 轉換為 TCP，也不代表節點一定具備該服務所需的 UDP 轉送能力。

嗅探通常需要等待連線初期的資料。連接埠範圍設得太寬，會讓大量非預期協定的連線進入嘗試流程，增加排錯難度。對遊戲、即時語音與自訂服務，請先確認協定，再決定是否納入。若連線建立緩慢，可比較關閉嗅探與限定連接埠後的結果；只有在變化明確且可重複時，才將問題歸因於嗅探，不要只憑一次偶然成功就下結論。

略過清單與分階段驗證

skip-domain 用於排除不適合嗅探的名稱，常見情況包括內部網域、需保留原始目標的服務，或已確認有相容性問題的業務。它與 Fake-IP 篩選清單用途不同：前者限制嗅探，後者改變 DNS 回應。同一網域出現在其中一份清單，不代表會自動加入另一份。若需要同時調整，請分別註明原因，避免日後刪除一項設定時，另一項例外仍被遺留。

可分三個階段進行驗證。先保留原始設定，記錄是否顯示網域及實際出口；接著只啟用嗅探，檢查是否補上網域及規則是否改變；最後僅在確有需要時嘗試目標覆寫，並比較連線位址與服務表現。每個階段都要建立新連線，並保留可還原的設定檔。只需暫時提高記錄層級，以足以觀察問題為限；排錯結束後請恢復日常層級，減少不必要的網域與瀏覽記錄留存。

本機覆寫與多訂閱合併

訂閱設定與本機偏好有不同的維護週期。訂閱提供者負責更新節點、策略與規則；本機使用者則維護監聽連接埠、DNS、業務例外與接管範圍。直接編輯下載的訂閱檔案，下一次更新可能就會覆蓋修改；將本機內容拆分為覆寫層，才能持續重複使用。請留意，覆寫並非 mihomo 統一規定的介面功能：不同 Clash 用戶端可能使用合併檔案、指令碼、圖形選項或設定範本，實際套用順序必須在用戶端中確認。

原始設定、覆寫層與執行設定

建議分別保存三份資料：訂閱提供的原始檔案、使用者維護的覆寫內容，以及用戶端交給核心的最終執行檔案。排查問題時應以最後一份為準。介面中的開關可能在產生設定時覆寫 YAML，同一欄位也可能被範本重複指定。若原始檔案中已啟用 DNS，但執行檔案沒有對應區塊，繼續編輯原始檔案也無法解決問題；應找出產生設定的順序與後續覆寫來源。

映射結構與清單結構的合併方式通常不同。DNS 參數有時會依欄位合併，但 rules、proxy-groups 與節點清單可能會被整份取代。不能假設用戶端行為等同於通用 YAML 合併工具。測試時先只覆寫一個可觀察欄位，例如記錄層級，確認執行檔案有相應變化後，再新增規則清單。若整份規則清單被取代，必須明確保留訂閱規則，不要誤以為「新增一條」只會附加在原清單後面。

透過提供者統一管理節點來源

合併多份訂閱不一定要拼接兩份完整 Profile。較容易維護的做法，是將支援的節點來源設為多個 proxy-providers，主要設定只維護一套策略與規則。以下示範兩個 HTTP 提供者的結構，網址僅供教學，請在本機替換為有效且相容的節點來源。並非所有完整訂閱都能直接作為節點提供者使用；匯入前請確認回應格式，尤其要確認是否包含可用的 proxies 資料。

proxy-providers:
  source-a:
    type: http
    url: https://example.com/provider-a.yaml
    path: ./providers/source-a.yaml
    interval: 3600
  source-b:
    type: http
    url: https://example.org/provider-b.yaml
    path: ./providers/source-b.yaml
    interval: 3600

proxy-groups:
  - name: 合併出口
    type: select
    use:
      - source-a
      - source-b
    proxies:
      - DIRECT

每個提供者都應使用獨立路徑，避免不同來源寫入同一個快取檔案。更新間隔應依來源安排，必要時再手動更新，不要強迫兩個來源都採用過短的更新週期。若節點名稱重複，介面選擇與記錄判讀都容易混淆；請使用用戶端支援的名稱整理或提供者覆寫機制，加入來源識別資訊。不要在名稱中放入真實訂閱憑證，也不要透過清空名稱內容來處理重複問題。

本機規則應放在明確的位置

新增本機例外時，先確認插入位置。若規則加在訂閱中的 MATCH 後面，通常不會再被比對。較合理的做法是將少量本機規則放在前面，再接上訂閱原有規則或規則提供者。若用戶端提供「前置規則」與「後置規則」選項，也應檢查最終順序，尤其要留意範本是否會自動加入兜底項目。一次新增大量例外，會讓業務出現異常時難以判斷是哪條規則改變了路徑。

合併後也要檢查策略組引用。原訂閱中的規則可能引用「自動選擇」，而新範本只定義「合併出口」；即使節點全數匯入，未定義的策略名稱仍會造成設定錯誤。規則提供者名稱、節點提供者名稱與策略組名稱屬於不同的引用關係，不能只做全文取代。請先列出各類定義，再逐一確認引用；修改名稱時，也要同步檢查規則、組內成員與控制面板的顯示。

驗證語法與功能回歸

若可直接使用核心命令列，可透過設定檢查確認結構與引用關係。以下命令需要系統能執行 mihomo，且目前目錄中的檔案確實存在；桌面用戶端也可能提供設定檢查功能。語法測試通過，不代表節點憑證有效、規則來源可下載或所有服務都正常，因此仍須進行功能回歸測試。建議優先檢查本機服務、常用網站，以及一項需要代理的服務，並分別查看連線詳細資料。

mihomo -t -f ./config.yaml

每次更新訂閱後，都應抽查執行設定是否仍包含本機 DNS、例外規則與接管設定。記錄簡短的變更內容，註明修改欄位、目的與還原方式，比保留大量難以辨認的備份檔案更有用。若更新後無法啟動，先還原到最近可用的設定，再參考啟動當機時的記錄檔排查方式檢查語法、路徑與權限，避免一次清空所有 Profile。

外部控制面板

外部控制介面可用來讀取執行狀態、切換策略、查看連線及管理部分核心功能。面板只是將介面視覺化的用戶端，不是另一套代理核心。能開啟面板頁面，不代表已連線至目前的 Clash 用戶端；請確認控制位址、驗證方式與執行個體。面板可能連到舊程序，但系統代理卻指向新的程序。若出現「切換成功但連線未變」的情況，請先確認控制對象，不要立即重新安裝軟體。

先綁定本機，再考慮遠端存取

external-controller 用來設定 HTTP 控制介面的監聽位址。一般桌面使用情境建議綁定 127.0.0.1，讓介面只接受本機連線。secret 是介面的存取密碼，請在本機設定長度足夠且專用的密碼。以下刻意只展示監聽設定與本機介面目錄，不提供可直接複製的公用密碼；使用外部面板前，請在自己的設定中補上驗證資訊。控制密碼請勿與節點密碼或訂閱權杖共用。

external-controller: 127.0.0.1:9090
external-ui: ./ui

external-ui 指向已備妥的面板靜態檔案目錄，單靠這行設定不會自動產生完整介面。相對路徑仍取決於核心工作目錄；用戶端也可能內建面板並自動設定路徑。請先確認入口檔案存在且核心可以讀取，再開啟面板。若只看到空白頁面或資源載入失敗，請檢查介面目錄與靜態資源路徑；不要將這類前端載入問題誤判為代理節點故障。

介面驗證與瀏覽器限制

一般 HTTP API 使用 Bearer 驗證，也就是在請求中加入 Authorization 標頭。面板通常會透過連線設定儲存控制位址與密碼；填妥後先讀取基本狀態，再嘗試切換策略。瀏覽器跨來源限制與介面驗證是不同層次：即使密碼正確，仍可能遭跨來源政策阻擋。若使用不同來源的面板，請依核心支援的 CORS 設定限制可信來源，不要為了排錯就允許任意網站存取本機控制介面。

透過 HTTPS 頁面存取 HTTP 控制位址時，也可能受到混合內容限制；控制介面不在本機時尤其要留意。不要長期以關閉瀏覽器安全功能的方式處理。優先使用用戶端內建面板，或將面板與控制服務安排在合適的同源路徑。若必須遠端管理，請使用受控隧道，或具備驗證與 TLS 的管理入口，並明確限制可存取的使用者與網路範圍；控制連接埠不能當作一般公開網頁連接埠使用。

先執行唯讀檢查

以下命令會讀取環境變數中的本機密碼，不會將真實值寫入文件。執行前請先在自己的終端機環境中設定 MIHOMO_SECRET；若未設定，命令會提前報錯，而不是送出空白驗證資訊。收到成功回應代表該位址的介面可以存取，但仍需確認它是否為目前的執行個體。查看連線與記錄時，只保留排錯所需資訊，避免公開包含存取網域與網路位址的完整結果。

: "${MIHOMO_SECRET:?請先在本機設定控制密碼}"
curl --fail --silent --show-error \
  -H "Authorization: Bearer ${MIHOMO_SECRET}" \
  http://127.0.0.1:9090/configs

唯讀檢查正常後，再使用面板切換一個手動組，並建立新連線確認策略鏈。直接呼叫 API 時，還要處理名稱的 URL 編碼；名稱含空格或中文時，不可直接拼接後就假設所有工具都會正確轉換。修改操作通常只影響執行狀態，不一定會寫回訂閱檔案；重新載入或重新啟動後能否保留，取決於快取與用戶端的儲存機制。需要長期生效的欄位，仍應在正確的設定層中維護。

控制連接埠與代理連接埠分開排查

控制介面的連接埠供管理使用；HTTP、SOCKS 或混合代理連接埠則供業務連線使用，兩者不能互換。若將控制連接埠填入瀏覽器的系統代理設定，網頁將無法正常存取；面板若將混合代理連接埠填作控制位址，也無法取得策略清單。檢查設定時，請明確標示各連接埠用途，並確認是否被其他程序占用。若同時執行多個執行個體，請為每個執行個體使用獨立的工作目錄與控制連接埠，避免快取、規則檔案與介面操作互相干擾。

面板連線失敗時，可依回應階段逐層排查：無法建立連線，檢查監聽位址、程序與防火牆；回應未授權，檢查密碼與請求標頭；頁面能開啟但資料載入失敗，檢查控制位址、跨來源限制與瀏覽器主控台。若策略切換已生效但舊業務沒有變化，請回頭檢查既有連線重用問題。不要為了排除本機連線錯誤，就暫時開放所有監聽位址；本機管理不需要讓整個區域網路都能存取介面。

建立可重複執行的設定檢查流程

完整檢查流程應維持固定順序：先確認目前的 Profile 與執行個體，再核對最終 YAML；接著檢查提供者是否載入、策略組是否有成員，以及規則是否命中；然後驗證 DNS 與接管路徑，最後才調整嗅探或面板。每次只修改一個因素，並記錄原始值與觀察結果。需要返回快速入門流程時，請繼續閱讀使用說明；想依具體狀況排查，請前往疑難排解，不必從頭重建已正常運作的設定層。