開發者必學：用Clash TUN模式讓Git與終端工具順暢連線

1. TUN 為什麼能接管終端機流量

瀏覽器可以開啟網站，但 git clone、npm install 或 docker pull 卻逾時，常見原因是這些命令列程式沒有使用系統 HTTP 代理。系統代理通常只對主動讀取代理設定的應用程式生效；有些終端工具會遵循它，有些則不會。Clash 的 TUN 模式會建立虛擬網路介面，配合路由及封包轉送，將符合條件的 IP 流量送入核心，因此不必要求每個程式都理解 HTTP 代理設定。

要先區分「接管流量」與「選擇出口」：TUN 負責讓連線有機會進入核心，規則模式及規則清單才負責決定連線直連或走哪個代理策略。開啟 TUN 不代表所有流量必然走代理，也不代表 GitHub 等網站會自動命中代理規則。若 Git 使用 SSH 遠端，連線通常走 TCP 22；設定 http.proxy 不會把 SSH 連線轉成 HTTP 代理，但 TUN 可以在路由及規則允許時接管這條 TCP 連線。

不同用戶端的選項名稱和實作可能不同。Clash Verge、Clash Verge Rev 等圖形介面通常會提供 TUN 開關；核心設定範例則常見於 mihomo。請以目前用戶端實際使用的核心版本、設定頁面及啟動日誌為準，不要只因為 YAML 能匯入，就假設每個欄位都受支援。

先做最小驗證

1. 在用戶端確認目前執行的是支援 TUN 的核心，記下核心版本，並切換至 Rule／規則模式。
2. 啟用 TUN；如用戶端要求授權或安裝網路元件，依作業系統提示完成。Windows 可能需要系統管理員權限，macOS 則可能要求核准網路或系統延伸功能。
3. 在連線清單中觀察一次新的終端請求，確認連線有進入核心，並記下目標、命中規則與出口策略。
4. 只測試一個失敗的命令。不要同時更換 DNS、代理節點、規則和 TUN 設定，否則難以判斷是哪一項改動產生效果。

2. 啟用 TUN 並確認路由與 DNS

使用圖形介面時，先在設定中尋找「TUN 模式」或相近名稱，再檢查用戶端是否顯示核心已啟動、服務已就緒或權限已取得。某些用戶端會另外提供「自動路由」「嚴格路由」「DNS 劫持」等選項；它們的可用性、預設值和互動方式會隨核心版本改變。若選項未出現，先確認核心類型及版本，不要直接貼上其他核心的設定。

以下是 mihomo 常見的 TUN 設定形狀，僅供了解欄位用途，不是可直接覆蓋現有設定的完整設定檔。請合併到目前生效設定的 tun 區段，保留既有的節點、策略群組、DNS 和規則；如果用戶端透過覆寫機制管理設定，也要確認修改內容沒有被訂閱更新覆蓋。

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

mode: rule
log-level: info

• enable：啟用 TUN 介面。介面成功建立不等於所有流量已正確路由。
• stack：指定核心使用的網路堆疊；支援值與平台行為可能因 mihomo 版本而異，請查閱目前版本文件。
• auto-route：請核心協助建立路由。若系統有 VPN、虛擬機器或企業網路，路由優先順序可能互相影響。
• strict-route：控制路由接管的嚴格程度；啟用後仍須注意區域網路、區域網域及其他介面的相容性。
• dns-hijack：將符合條件的 DNS 請求交由核心處理。它不會自動修正所有應用程式的 DNS，也不代表 DNS 上游一定可用。

若設定檢查失敗，先移除不支援或不確定用途的欄位，再依目前核心文件逐項加回。若設定檢查通過但沒有連線，請比較系統路由、TUN 狀態及核心連線清單。測試時先關閉其他 VPN，確認沒有另一個虛擬網路介面改寫預設路由；測試完成後再逐一恢復其他網路工具。

3. 為開發服務設計規則分流

連線進入核心後，規則依序比對；先符合的規則通常就決定出站策略。以下片段假設設定中已有名稱完全一致的「開發代理」策略群組。若現有群組名稱不同，請替換規則中的名稱；不要把這段當成完整的節點或代理設定。服務使用的網域可能因登入、套件儲存、容器映像和 CDN 而不同，應從連線清單確認實際目標，再補充必要規則。

rules:
  - DOMAIN-SUFFIX,github.com,開發代理
  - DOMAIN-SUFFIX,githubusercontent.com,開發代理
  - DOMAIN-SUFFIX,npmjs.org,開發代理
  - DOMAIN-SUFFIX,pypi.org,開發代理
  - DOMAIN-SUFFIX,pythonhosted.org,開發代理
  - DOMAIN-SUFFIX,docker.io,開發代理
  - MATCH,DIRECT

這是依網域後綴比對的簡化示例，不保證涵蓋服務的所有端點。GitHub 的下載資源、套件登錄服務和 Docker 映像可能連到不同網域；若只把主站加入規則，登入頁面可用而套件下載失敗並不奇怪。請在出問題時查看核心連線清單，逐筆記錄網域、命中規則、代理群組及失敗訊息，再決定是否增加精確網域規則。避免使用範圍過大的關鍵字規則，以免不相關的開發或企業流量也被導向代理。

若連線清單顯示 DIRECT，先確認是否命中 MATCH,DIRECT 或其他更前面的直連規則；若顯示代理群組但仍失敗，再檢查群組目前選中的節點與錯誤階段。規則只能選擇已有的出口，不能建立不存在的代理伺服器。

4. 設定 Git、npm、PyPI 與 Docker

TUN 正常時，許多不支援系統代理的 TCP 程式也能透過路由進入核心，通常不需要另外設定每個工具。若需要快速區分「工具代理設定」與「TUN 路由」問題，可以暫時為單一命令指定本機 HTTP 代理。以下以常見的 HTTP／SOCKS 混合監聽埠 7890 為例；請換成用戶端實際使用的 HTTP 代理埠，不要因為埠號常見就假設本機正在監聽它。

Git：先確認遠端是 HTTPS 還是 SSH

Git 的 HTTPS 遠端可以透過 HTTP 代理連線。可先用單次命令測試，避免把尚未驗證的代理設定永久寫入使用者或專案設定：

git -c http.proxy=http://127.0.0.1:7890 ls-remote https://github.com/OWNER/REPO.git

將範例中的擁有者與儲存庫名稱換成實際目標。若單次測試可用，再考慮使用 git config --global http.proxy 設定全域代理；若不再需要，使用 git config --global --unset http.proxy 移除。代理設定可能寫入明文組態，不要把含帳號、密碼或權杖的代理 URL 貼進公開儲存庫。SSH 遠端不會因設定 http.proxy 而改走 HTTP 代理；請透過 TUN 路由與相應規則處理，或依組織政策設定 SSH 專用跳板方式。

npm 與 PyPI：使用工具設定前先確認 TUN

npm 通常會向 registry 及套件下載來源發出 HTTPS 請求。先檢查 npm config get registry，並用 npm ping 或一個小型套件安裝測試連線；若要測試明確代理，可使用 npm --proxy=http://127.0.0.1:7890 ping。不同 npm 版本對代理設定的採用方式可能不同，請以命令輸出及連線清單驗證，不要假設加上參數後就一定經過代理。

Python 的 pip 可用單次參數測試 HTTPS 代理，例如 python -m pip --proxy http://127.0.0.1:7890 index versions 包名；若目前 pip 版本不支援該子命令，可改用一次套件安裝測試，並留意是否真的開始連線。永久設定前先確認電腦是否共用；全域代理可能影響公司內部 PyPI 鏡像或其他網路環境。索引頁面與套件檔案可能由不同主機提供，必須檢查整段下載流程。

Docker：確認 daemon，而不只看終端機

docker pull 發出的網路請求通常由 Docker daemon 或 Docker Desktop 管理的服務完成，不一定由目前的終端程序直接發出。因此，終端機能使用代理不代表 Docker daemon 自動沿用相同設定。Docker Desktop 還會透過虛擬化網路處理容器與映像流量；Linux 上的 Docker Engine 則受 daemon 網路與服務設定影響。若 docker pull 失敗而其他終端工具正常，請先確認 daemon 的代理設定、Docker Desktop 網路狀態及錯誤中的目標主機，再檢查 TUN 是否能看見相應連線。不要把宿主機代理環境變數誤當成所有容器及 daemon 都已套用的設定。

5. Windows 與 macOS 的常見故障排查

兩個平台都應先按照「TUN 是否啟動、流量是否進入核心、規則是否選對出口、遠端連線是否成功」的順序排查。若程式沒有出現在連線清單中，優先檢查系統路由和權限；若已出現但走錯出口，檢查規則順序與策略群組；若出口正確但逾時，則檢查節點、DNS、遠端服務或防火牆。這個順序能避免把每種錯誤都歸因於代理節點。

Windows：服務與虛擬網路介面

若用戶端提示需要管理員權限，請先依介面指示授權，再確認 TUN 服務或虛擬介面處於啟用狀態。某些電腦同時安裝公司 VPN、虛擬機器軟體或其他網路過濾程式，可能造成路由競爭；測試時可暫時停用非必要的 VPN，並觀察切換 TUN 前後的網路狀態。若只有某一個程式無法進入核心，查看該程式是否被排除、是否使用自訂網路堆疊，以及安全軟體是否封鎖虛擬介面流量。

macOS：授權與其他 VPN 衝突

macOS 可能要求核准網路延伸功能或 VPN 設定。若拒絕授權、系統升級後權限狀態改變，或同時啟用另一個 VPN，TUN 介面可能無法正常接管路由。依用戶端提示到系統設定檢查相關授權，再重新啟動用戶端並確認核心啟動記錄。不要只依據選單列圖示判斷成功；應以介面狀態、路由及實際連線紀錄共同確認。

用診斷結果定位故障層

• 連線不在清單中：檢查 TUN 是否啟用、程式是否被排除、流量是否由 Docker daemon 等背景服務發出，以及系統路由有沒有指向 TUN。
• 連線出現但命中直連：確認規則模式、規則順序、實際目標網域與預設規則；不要只根據命令名稱推斷它會比對哪個網域。
• 命中代理但連線逾時：檢查策略群組當前選擇、節點可用性和核心日誌中的錯誤位址。單一服務失敗不等於所有代理都不可用。
• 解析失敗或網域規則不生效：確認 DNS 查詢是否交給預期的解析器，並注意某些應用程式會使用自己的 DNS 實作或快取。

常見問題