GitHub 專案無法 clone、npm 套件下載停在逾時，或 Docker 映像拉取失敗，不一定是節點故障。常見原因是終端機程式沒有使用圖形介面的系統代理設定，或實際發出連線的是另一個服務，例如 Docker daemon。Clash 的 TUN 模式可透過虛擬網卡接收符合路由條件的 IP 流量，讓未設定 HTTP 代理的程式也有機會經過 Clash；但它不會自動修正 DNS、規則或 Docker 的獨立網路環境。
工程師必看Clash TUN設定：Git、npm與Docker命令列連線實戰指南
先分清 TUN、系統代理與終端機代理
系統代理通常只對會讀取系統代理設定的應用程式生效。瀏覽器可能直接使用作業系統設定，但 Git、npm、容器引擎或自行編譯的工具，可能忽略該設定。結果就是瀏覽器可以開啟網站，命令列仍出現連線逾時。
- 系統代理：設定 HTTP 或 SOCKS 代理位址，讓支援系統代理的應用程式使用。這不是作業系統強制攔截所有流量的機制。
- 環境變數代理：透過
HTTP_PROXY、HTTPS_PROXY等變數告知程式應連到哪個代理入口。只影響會讀取這些變數的程式。 - TUN：核心建立虛擬網路介面，依作業系統路由與 mihomo 規則處理捕捉到的流量。它通常需要管理員或系統網路權限，也可能受防火牆、VPN 和其他虛擬網卡影響。
TUN 與代理變數並非只能二選一。一般應用程式可由 TUN 接收流量；Git 或 npm 也可明確設定本機 HTTP 代理入口，方便排除問題或指定連線方式。兩種方式同時使用時，要留意程式連到的本機代理入口是否又被 TUN 規則處理，避免錯誤路由或形成不必要的轉送。
以下設定只示範 mihomo 的基本 TUN 開關，並不會提供代理節點，也不代表所有用戶端都使用相同選單名稱。請先備份設定檔，確認使用的核心支援這些欄位，再透過用戶端支援的設定覆寫功能套用。
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: trueauto-route 會協助建立流量路由，auto-detect-interface 則用於偵測出口介面；不同作業系統和用戶端的實際行為可能不同。啟用後，請在用戶端確認 TUN 狀態已啟動，並查看核心日誌是否出現權限不足、路由建立失敗或介面衝突。若設定檔有 dns 或規則設定，也要確認它們與目前網路環境相容。不要在不理解作用的情況下同時修改路由、DNS 和防火牆。
依序確認 TUN 是否接到命令列流量
先測代理入口，再測 TUN 路由，最後才測特定工具。這樣可以區分本機核心未監聽、遠端連線失敗，以及應用程式本身設定不相容。測試前記下開始時間和目標網域，方便在 Clash 的「連線」或核心日誌中搜尋相同請求。
- 確認用戶端目前選取了有效設定檔，核心正在執行，且已選擇可用的代理策略組。只看到設定檔名稱，不代表核心已成功載入。
- 確認 TUN 已啟用，並檢查系統是否跳出權限要求。若日誌顯示無法建立介面或路由，先處理該錯誤，不要直接把問題歸因於節點。
- 在瀏覽器或終端機向一個已知可測試的網站發出請求，同時查看 Clash 連線記錄。記錄中應能看到請求的網域或目標 IP、命中的規則和所用策略。
- 若請求完全沒有出現在記錄中，檢查 TUN 是否啟動、應用程式是否使用另一個網路環境，以及目前路由是否繞過虛擬介面。
- 若請求已出現在記錄中但失敗，查看規則命中結果、DNS 解析與節點連線狀態。此時問題通常已進入 Clash 的處理流程，反覆設定終端機代理變數未必有幫助。
在 macOS 或 Linux 終端機，可以用以下命令檢查 HTTPS 請求及回應標頭。將網域換成實際要測試、且允許存取的目標：
curl -I --connect-timeout 10 https://registry.npmjs.org/Windows PowerShell 中請使用 curl.exe，避免某些版本將 curl 對應到 PowerShell 命令別名：
curl.exe -I --connect-timeout 10 https://registry.npmjs.org/收到 HTTP 回應只代表這次請求取得了回應，不保證每個 Git、npm 或 Docker 目的地都能連線。若名稱解析錯誤，先檢查 DNS 與 TUN 的 DNS 處理；若連線逾時，則比較 Clash 記錄中是否有請求、命中哪條規則，以及使用哪個策略。不要只依瀏覽器成功就認定整台電腦的所有流量都已經過代理。
為 Git 與 npm 設定可驗證的代理方式
Git：先用單次測試，再決定是否寫入設定
如果 TUN 已確認可接收終端機連線，Git 通常可直接測試：
git ls-remote https://github.com/OWNER/REPOSITORY.git將範例路徑換成有權限存取的公開或私人儲存庫。若命令逾時，先查看 Clash 連線記錄中是否出現 GitHub 網域。如果沒有記錄，檢查 TUN 路由、Git 執行環境或公司網路政策；如果有記錄，則檢查規則、節點及 DNS。私人儲存庫另外需要正確的 SSH 金鑰或 HTTPS 憑證，代理成功不會取代 GitHub 權限驗證。
也可以讓 Git 明確使用本機 HTTP 代理入口。以下以 127.0.0.1:7890 為例，前提是該連接埠實際提供 HTTP 代理或 mixed-port 服務：
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
git config --global --get http.proxy
git config --global --get https.proxy這裡的 https.proxy 值仍可能是以 http:// 開頭，因為它表示 Git 透過 HTTP CONNECT 請求連接 HTTPS 網站，不代表目標網站改用不加密的 HTTP。若只想對單次命令測試，可使用：
git -c http.proxy=http://127.0.0.1:7890 \
ls-remote https://github.com/OWNER/REPOSITORY.git測試結束後，若不希望 Git 一直使用代理，可移除全域設定：
git config --global --unset http.proxy
git config --global --unset https.proxy若 Git 使用 SSH 形式的遠端網址，例如 [email protected]:OWNER/REPOSITORY.git，上述 HTTP 代理設定不一定會套用到 SSH 連線。請先確認遠端網址格式和 SSH 用戶端設定，不要把 HTTPS 的成功測試當成 SSH 也已通過。
npm：檢查註冊表與代理設定
先查看目前 npm 使用的註冊表並直接測試連線。官方 npm registry 常見網址為 https://registry.npmjs.org/，但專案或組織可能使用私有 registry：
npm config get registry
npm ping若要測試本機 HTTP 代理入口，可在 npm 設定中指定代理。請先確認連接埠與核心提供的服務種類相符：
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm ping不要為了解決憑證錯誤而直接設定 strict-ssl=false。停用 TLS 憑證驗證會降低連線安全性，不能修復 DNS、錯誤代理位址或節點中斷。公司網路若使用自訂憑證，應依管理單位提供的憑證與設定處理。完成測試後，若想回到由 TUN 或其他設定接管，可移除 npm 的代理值：
npm config delete proxy
npm config delete https-proxy如果 npm ping 成功但安裝仍失敗，查看錯誤指向的實際套件 registry、套件網址或 Git 相依來源。套件安裝過程可能連到多個網域；只測通 registry 根網址，不代表所有相依資源都可用。
Docker：分開排查 daemon、建置與容器
Docker 命令列不是唯一發出網路請求的元件。docker pull 通常由 Docker daemon 負責連線；Docker Desktop 又可能透過自己的虛擬化網路處理流量。因此，宿主機瀏覽器或一般終端機通過 TUN 測試，不足以證明 daemon 一定使用相同路徑。
- 映像拉取失敗：查看 Docker daemon 的錯誤時間與 registry 網域，並確認 daemon 本身是否能透過目前網路連線。
- 建置期間下載失敗：區分 Dockerfile 中的
RUN命令、建置引擎與 daemon 的連線。BuildKit 的代理參數和 Docker daemon 的代理設定用途不同。 - 容器啟動後無法連線：容器內有獨立的網路命名空間和 DNS 設定。宿主機 TUN 可用，不代表容器內的路由、名稱解析與代理環境已正確設定。
先執行一個小型映像拉取測試，並同步查看 Docker daemon 日誌與 Clash 連線記錄：
docker pull hello-world若 Clash 記錄完全沒有 Docker registry 的請求，優先檢查 Docker Desktop 的代理設定、虛擬網路路徑或作業系統對 daemon 的路由方式。Docker Desktop 可在其設定介面檢查 Proxy 選項；Linux 上的 Docker Engine 則可能以 systemd 服務環境或 daemon 設定管理代理。各平台做法不同，請依安裝方式確認，不要把桌面版設定步驟直接套用到 Linux 伺服器。
建置時可將代理作為建置參數傳入，但請勿把含帳密的代理網址寫進 Dockerfile 或映像層。以下僅示範環境變數的傳遞形式；要使用前，先確認建置工具與專案是否支援對應的 build argument：
docker build \
--build-arg HTTP_PROXY=http://host.docker.internal:7890 \
--build-arg HTTPS_PROXY=http://host.docker.internal:7890 \
-t local-test .host.docker.internal 在部分 Docker Desktop 環境中可用來指向宿主機，但不保證所有 Linux 安裝或自訂網路都支援。若建置環境無法解析此名稱，應依平台檢查宿主機可達位址和 daemon 設定。建置代理也不會自動替已執行的容器設定代理；容器是否需要代理，應依應用程式需求個別配置。
依錯誤現象縮小排查範圍
| 現象 | 優先檢查 | 建議動作 |
|---|---|---|
| 瀏覽器正常，Git 和 npm 都逾時 | TUN 狀態、核心連線記錄、命令列環境 | 用 curl.exe 或 curl 測試 registry，確認請求是否出現在 Clash 記錄 |
| Git 可用，npm 下載失敗 | npm registry、npm 代理設定、套件相依網址 | 檢查 npm config get registry，比對錯誤中的實際網域 |
| GitHub 網頁可用，Git clone 失敗 | 遠端網址是 HTTPS 或 SSH、帳戶權限、憑證 | 使用 git ls-remote 測試同一遠端，勿將認證錯誤誤判為代理逾時 |
| 一般命令列正常，Docker pull 失敗 | Docker daemon 或 Docker Desktop 代理與虛擬網路 | 查看 daemon 日誌和 Clash 記錄，必要時設定 daemon 層代理 |
| 映像可拉取，容器內仍無法連線 | 容器 DNS、網路模式和容器內代理環境 | 在容器內測試名稱解析與目標連線，分開處理宿主機與容器網路 |
| 所有工具都顯示名稱解析錯誤 | 目前 DNS 設定、TUN DNS 處理與網路限制 | 先確認目標網域是否解析，再看 Clash DNS 與核心日誌，不要只更換節點 |
若 TUN 啟用後連公司內網、印表機或本機開發服務也異常，請檢查規則是否將區域網路流量送往不適合的出口，以及虛擬網卡是否與其他 VPN 衝突。不要直接停用防火牆或把所有流量改成全域代理作為長期處理方式。先保留原設定，再逐項測試，才知道是哪一個變更影響連線。
常見問題
啟用 TUN 後，還需要設定 HTTP_PROXY 嗎？
不一定。TUN 可處理符合路由條件、進入虛擬介面的流量；環境變數則讓支援它的程式明確連到代理入口。若 TUN 已接管且測試正常，可先不設定變數。若需要針對單一工具排查，則可暫時使用變數或工具自己的代理設定，測完後移除不再需要的設定。
為什麼 Docker pull 不經過 TUN，但 Git 會？
因為 Docker Engine 或 Docker Desktop 的 daemon 可能透過服務帳戶、虛擬機器或獨立網路環境發出請求，不一定等同於目前登入使用者的終端機流量。查看 Docker 端代理設定、daemon 日誌及 Clash 連線記錄，才能確認請求實際從哪裡出去。
TUN 已顯示啟用，為什麼命令仍然逾時？
啟用狀態只表示功能已開啟，不代表目標連線成功。請確認命令請求是否出現在 Clash 記錄；沒有請求時檢查路由、權限和執行環境，有請求時再檢查 DNS、命中規則、策略組與節點狀態。
連接埠一定要使用 7890 嗎？
不是。7890 只是常見示例，實際 HTTP 或 mixed-port 可能是其他數值，也可能由用戶端覆寫設定。請從執行中的設定檔或用戶端連接埠頁面確認；若對應連接埠沒有提供 HTTP 代理服務，Git 或 npm 使用該入口就會失敗。