1. 收集日誌：先固定請求，再提高日誌層級

Clash 用戶端介面日誌與核心執行日誌屬於不同層級。介面日誌可能記錄訂閱下載、服務啟動及設定合併；核心日誌則主要記錄監聽連接埠、DNS、規則比對及連線出站。網頁無法開啟時，先確認核心已啟動，再檢查該次請求是否進入核心。只有用戶端介面的錯誤截圖，通常不足以判斷是節點或規則出了問題。

最小重現紀錄

  1. 記下用戶端名稱、用戶端版本、核心名稱及完整版本號。Clash 原版與 mihomo 支援的欄位不同，不能只寫「最新版」。
  2. 記下目前的設定名稱、執行模式，以及是否啟用系統代理或 TUN。排查規則時請使用規則模式，避免全域模式略過預期規則。
  3. 清空目前的日誌檢視畫面並記下時間，只造訪一個有問題的網址。等待約 10 秒後停止反覆重新整理，並儲存同一時段的日誌。
  4. 同時查看連線清單中的目標、命中規則、策略群組及最後使用的節點。日誌未提供的出站資訊，可從連線清單補齊。

需要更多細節時，可在目前用戶端的日誌頁面調整層級；若介面沒有相關選項，可透過其支援的設定編輯或覆寫功能設定下列欄位。訂閱用戶端可能會重新產生執行設定，請確認最後生效的值；只修改之後會被覆蓋的訂閱快取檔案並不足夠。

log-level: debug
層級常見用途閱讀重點
debug短時間重現疑難問題DNS、連線及核心提供的除錯細節
info日常執行狀況監看啟動資訊、規則命中及連線紀錄
warning篩選異常事件連線失敗、資源載入異常
error留意較嚴重的錯誤設定載入及關鍵元件錯誤
silent關閉一般日誌輸出不適合用於故障重現階段

個別訊息的層級由核心決定，warning 不一定代表整個代理服務已停止。重現問題後，請將層級恢復為 info。分享日誌前，請隱藏訂閱網址中的權杖、節點密碼、控制介面金鑰及個人存取網域；連接埠、錯誤類型及規則順序則應保留。

2. dial tcp 逾時：區分節點連線與目標連線

dial tcp 表示程式正在建立 TCP 連線，不等於「DNS 出錯」，也不能只憑這兩個字就判定節點失效。關鍵在於後方的位址屬於哪一端：代理伺服器、直連目標，還是代理鏈中的下一個節點。以下片段僅示範錯誤格式，使用的是文件範例位址，並非可用節點。

dial tcp 192.0.2.10:443: i/o timeout
dial tcp 192.0.2.10:443: connect: connection refused
dial tcp [2001:db8::10]:443: connect: network is unreachable

三種錯誤的排查方向

  • i/o timeout：連線或讀寫作業未能在期限內完成。檢查該行對應的節點位址、連接埠、出站介面及網路路徑，不要直接拉長逾時時間來掩蓋問題。
  • connection refused：通常表示收到明確拒絕。優先檢查連接埠設定、遠端服務是否正在監聽，以及本機或中間設備的拒絕策略。
  • network is unreachable：目前的網路堆疊沒有可用路徑。若目標是 IPv6 位址，先確認系統的 IPv6 路由，不要立刻歸因於節點密碼。

如果錯誤指向節點伺服器，先切換到同一策略群組中另一個已知可用的節點，再對同一目標重試。若只有特定節點失敗，請檢查該節點的伺服器網域、連接埠及協定參數；若多個節點同時失敗，則檢查本機網路、節點網域解析及代理迴圈。節點測速成功只代表測速涵蓋的請求成功，無法證明所有網站或 UDP 流量都正常。

如果連線清單顯示 DIRECT，問題可能出在目標網站的直連路徑。此時先確認命中的規則，不要在沒有證據時重新安裝用戶端。規則會依序比對，較前面的 DOMAIN-SUFFIX 或規則集可能已決定出站方式，後面的 MATCH 不會再改變結果。

3. DNS 解析失敗：逐層確認解析鏈

no such host 常見於名稱不存在，或解析鏈傳回否定結果；lookup ... i/o timeout 較可能表示 DNS 請求未能及時收到回應；SERVFAIL 則表示解析服務無法完成查詢。這些訊號代表不同問題，不能一律靠更換代理節點處理。

先確認正在解析哪個網域

  1. 目標網站網域：檢查核心 DNS 是否啟用、應用程式是否使用系統 DNS，以及 Fake-IP 請求是否確實進入核心。
  2. 節點伺服器網域：檢查節點網域的解析路徑。mihomo 可透過 proxy-server-nameserver 指定節點網域解析器，實際行為請以目前核心版本的文件為準。
  3. 加密 DNS 伺服器網域：檢查用來啟動解析的 default-nameserver。若上游解析器本身的網域無法解析，解析鏈就可能無法啟動。

以下是監聽本機 1053 連接埠的最小 DNS 診斷片段。請合併至現有且唯一的 dns 對應項目中，並保留其他符合目前環境需求的欄位。此設定以一般 DNS 作為排查工具，不是適用於所有網路環境的最終設定，也不會自動修改系統 DNS。

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: redir-host
  nameserver:
    - 223.5.5.5

已安裝 dig 的環境可直接測試這個監聽連接埠。以下兩個指令分別查詢 IPv4 與 IPv6 記錄；沒有 AAAA 記錄不代表 A 記錄解析失敗。

dig @127.0.0.1 -p 1053 example.com A
dig @127.0.0.1 -p 1053 example.com AAAA

如果本機監聽連接埠查詢成功，但應用程式仍回報解析失敗，請檢查應用程式內建的安全 DNS、瀏覽器 DNS 快取及實際接管路徑。如果監聽連接埠也無法查詢，再確認上游 DNS 是否可連線，以及啟用 respect-rules 等功能後是否形成解析依賴迴圈。不要同時更改上游、Fake-IP 及路由規則，否則難以判斷哪項改動有效。

4. 連接埠占用：找出監聽程序與實際代理連接埠

啟動時出現 bind: address already in use，通常表示監聽位址與連接埠發生衝突。Windows 也可能顯示「每個通訊端位址通常只允許使用一次」。permission denied 則應另外檢查權限、安全策略或連接埠保留狀況，不能一律歸因於已有程序占用。

先從錯誤行確認實際連接埠，再查對應的設定欄位。例如 mixed-port: 7890 同時提供 HTTP 與 SOCKS 代理入口；external-controller: 127.0.0.1:9090 則是管理介面，兩者用途不同。以下連接埠僅供排查示範，實際連接埠請以執行中的設定為準。

Windows：查看 7890 的監聽程序

netstat -ano | findstr :7890
tasklist /FI "PID eq 1234"

第一個指令也可能比對到遠端連接埠，請確認本機位址欄及 LISTENING 狀態。第二個指令中的 1234 是範例 PID，執行時請替換為第一個指令輸出中的實際程序編號。優先透過用戶端正常退出重複執行的執行個體，不要直接結束不明的系統程序。

macOS 與 Linux：只查詢 TCP 監聽程序

# macOS
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux
ss -ltnp 'sport = :7890'

Linux 顯示其他使用者的程序資訊時，可能需要管理員權限。若改用 7891，必須同步修改系統代理、瀏覽器手動代理或終端機環境變數；只改核心連接埠會讓應用程式繼續連線到舊連接埠。allow-lan 會影響區域網路的存取範圍，並非修復本機連接埠衝突的開關。

5. 設定解析錯誤：分別檢查語法、欄位與引用

設定無法載入時，應先處理啟動錯誤，再檢查網路。yaml: line ... 通常指向 YAML 解析問題；proxy ... not found 之類的訊息通常與引用名稱有關；協定類型不支援或欄位無法辨識，則可能是核心相容性問題。錯誤行是排查起點，真正的縮排錯誤也可能出現在前一段。

  • 縮排：使用空格，不要使用 Tab。同一層級的鍵保持相同縮排，清單項目在 - 後保留空格。
  • 重複鍵：不要在同一層級重複加入第二個 dns、rules 或 proxy-groups。不同解析器可能會回報錯誤或覆蓋內容，結果並不可靠。
  • 名稱引用：規則引用的策略群組、策略群組引用的節點，以及 RULE-SET 引用的規則提供者，都必須與定義名稱一致。
  • 核心能力：不能假設原版 Clash 都能讀取 VLESS、Hysteria2 等設定。請先確認實際執行的核心，而不只是查看用戶端名稱。
  • 遠端資源：規則集下載失敗屬於資源載入問題，不一定是 YAML 語法錯誤。請接著檢查相關提供者的 URL、檔案格式、快取路徑及下載時使用的網路路徑。

直接執行 mihomo 核心時，可先測試設定檔。以下指令要求目前目錄中有對應的可執行檔及設定檔；測試用設定應盡量與用戶端實際產生的執行設定一致。

# macOS / Linux
./mihomo -t -f ./config.yaml

# Windows PowerShell
.\mihomo.exe -t -f .\config.yaml

設定測試通過，只表示這次檢查未發現會阻止載入的問題，不代表節點可連線或所有規則集都能如預期運作。如果訂閱原始內容通過測試，但用戶端仍無法啟動，請檢查覆寫設定、指令碼合併結果及用戶端產生的設定差異。修改前先備份，每次只修正一種錯誤，再重新測試。

6. 系統代理與 TUN：用同一個請求比較接管路徑

「瀏覽器能開啟，終端機卻不行」通常需要檢查應用程式是否遵循系統代理。系統代理不會自動接管所有程式；TUN 則涉及虛擬網卡、路由及 DNS 接管，排查範圍更廣。沒有對照結果時，不要同時啟用多個代理工具和多個 TUN 執行個體。

先確認明確指定的代理入口

假設執行設定中的混合連接埠確實是 7890，可透過以下請求排除應用程式是否讀取系統代理的差異。Windows PowerShell 請使用 curl.exe，避免舊版環境中的命令別名影響結果；macOS、Linux 則可將指令名稱改為 curl。

curl.exe -v --connect-timeout 10 --max-time 20 --noproxy "" --proxy http://127.0.0.1:7890 https://example.com/

這個指令將連線階段逾時設為 10 秒、總時間上限設為 20 秒，方便比對日誌時間，並非實際測得的延遲。若無法連線至 127.0.0.1:7890，請先檢查監聽狀況；若代理通道已建立但 TLS 失敗，請檢查後續交握；收到 HTTP 回應後再判斷狀態碼，403 等回應不能直接視為代理入口故障。

接著比較 TUN 接管結果

如果明確指定代理成功，但一般應用程式請求失敗，請優先檢查系統代理設定、應用程式個別代理及 TUN 路由。啟用 TUN 後發生問題，可先保留設定副本，再暫時關閉 TUN，並以明確指定代理的結果作為對照。需檢查的欄位包括 tun.enable、auto-route 及 dns-hijack；實際支援情況及權限需求則視核心、用戶端與作業系統而定。

不要把 dns-hijack 理解成能攔截所有加密 DNS：一般 DNS 劫持設定主要處理符合條件的 DNS 流量，應用程式自行發出的 HTTPS DNS 請求仍可能走獨立路徑。如果日誌完全沒有對應連線，請先確認請求是否進入核心；若已進入，再依序檢查規則、出站、解析及交握階段。

7. 修復驗收：保留可重現的證據

關閉故障前，請用原本失敗的同一個網址再次測試，並確認日誌中的命中規則及出站節點符合預期。只看到首頁成功開啟一次，無法證明訂閱更新、DNS 及背景應用程式都已恢復正常。

  1. 啟動驗收：核心已完成載入，代理入口正常監聽，且未再次出現連接埠綁定錯誤。
  2. 請求驗收：原本的請求已成功，日誌中不再出現該請求的重複逾時或解析錯誤。
  3. 路徑驗收：直連與代理規則分別命中預期策略，TUN 開關狀態符合使用需求。
  4. 設定持久化：重新啟動用戶端或更新訂閱後，修改仍然生效，未被設定產生流程覆蓋。

若仍需回報問題，請整理「用戶端與核心版本、作業系統版本、重現時間、目標類型、相關設定片段、前後連續日誌及已執行的單項測試」。這些資訊比單獨截取最後一行 timeout 更有助於定位問題。欄位含義請參閱協定參考；規則、DNS 與 TUN 的概念差異請參閱概念速查。