開發者 GitHub、Docker 與 npm 網路加⁠速設定：日常開發一次配齊

先分清楚：代理程式與開發工具的連線路徑

開發工具的網路請求不一定經過瀏覽器。Git 可能由命令列程序直接連到 GitHub；Docker 映像檔通常由 daemon 或 Docker Desktop 背景服務拉取；npm 和 pip 則由套件管理器各自發出請求。即使桌面代理程式顯示已連線，只要工具沒有讀取系統代理、沒有設定代理環境變數，或連線模式沒有接管該工具的流量，請求仍可能走原本的網路。

先確認代理工具實際使用的本機 HTTP 或 SOCKS 連接埠，再逐一設定開發工具。以下範例以本機 HTTP 代理連接埠作為示意，7890 只是範例值，不代表所有用戶端都使用相同連接埠。請以目前用戶端的設定畫面為準；若工具只支援 HTTP 代理，就不要把 SOCKS 連接埠直接當成 HTTP 代理使用。

另一個常見誤解是將「VPN 已連線」等同於「所有程式都會走同一路徑」。系統層級 VPN、桌面代理用戶端、終端機環境變數和應用程式內建代理，是不同設定層。分流模式也可能讓特定網域或程序直接連線。測試時要分別確認網頁、命令列和容器映像檔是否符合預期，不要只看用戶端的連線狀態。

• ✅ 先查清代理協定與本機連接埠，再修改工具設定。
• ✅ 區分發出請求的是命令列工具、Docker daemon，還是 CI 執行器。
• ✅ 企業內部網域、套件服務與版本控制伺服器，應按團隊規範決定是否加入例外清單。
• ❌ 不要把「已連線」或「瀏覽器能開網頁」當成所有開發工具已通過代理的證據。

GitHub 與 Git：從命令列設定代理

若 Git 使用 HTTPS 位址，例如 https://github.com/組織/專案.git，可以透過 Git 的代理設定轉送 HTTP 與 HTTPS 請求。設定前先確認本機代理服務正在執行，並以小型公開專案測試連線；若公司 Git 伺服器必須直連，則不宜未經確認就套用全域代理。

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

git clone https://github.com/ORG/REPOSITORY.git

檢查目前設定可使用 git config --global --get http.proxy 和 git config --global --get https.proxy。若完成下載後需要恢復原狀，使用以下命令移除全域值：

git config --global --unset http.proxy
git config --global --unset https.proxy

全域設定會影響使用相同 Git 設定檔的其他 HTTPS 遠端，因此要留意內部程式碼庫、公司代理政策和不同工作環境的差異。若只有某個工作階段需要代理，可以改用環境變數，完成後再於該終端機視窗移除：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

git clone https://github.com/ORG/REPOSITORY.git

unset HTTP_PROXY
unset HTTPS_PROXY

上述 export 和 unset 適用於常見的 Unix shell。PowerShell 可在目前工作階段使用 $env:HTTPS_PROXY="http://127.0.0.1:7890" 設定環境變數，並以 Remove-Item Env:HTTPS_PROXY 移除。新開的終端機是否繼承設定，取決於變數是隻設在工作階段，還是另外寫入使用者或系統環境。

若 GitHub 使用 SSH 遠端位址，例如 [email protected]:ORG/REPOSITORY.git，以上 HTTP 代理設定不會自動轉成 SSH 代理。SSH 需要獨立的用戶端設定，而且可能受到公司網路、金鑰管理與伺服器政策限制；切換為 HTTPS 遠端通常較容易先驗證 HTTP 代理路徑，但是否可切換仍應符合專案規範。

遇到憑證錯誤時，先確認系統時間、作業系統與 Git 的憑證儲存，以及公司是否要求安裝受信任的根憑證。不要使用 git config http.sslVerify false 關閉 TLS 憑證驗證，也不要把代理的登入密碼直接放進可提交的設定檔。忽略憑證錯誤可能讓連線遭到攔截，不能當作一般加速設定。

Docker：設定映像檔拉取所使用的代理

docker pull 是由 Docker 引擎發出請求，Docker CLI 本身能使用代理，不代表背景引擎已取得相同設定。在 macOS 和 Windows 使用 Docker Desktop 時，優先檢查 Docker Desktop 的代理設定與目前版本提供的設定介面；Linux 上則要確認實際執行 Docker daemon 的服務管理方式。設定代理後，重新啟動相關服務，再用 docker pull 驗證。

Linux 常見做法是透過 systemd 為 Docker 服務設定環境變數。以下是結構示例，建立或修改服務覆寫檔之前，請依發行版和企業維運規範確認服務名稱及管理方式：

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,.internal.example"

修改服務設定後，需要重新載入 systemd 設定並重啟 Docker，再執行映像檔拉取測試。若無法連線，依序檢查代理是否能從 Docker daemon 所在的主機或執行環境到達、代理是否允許該目標，以及 NO_PROXY 是否錯誤地排除了目標網域。主機上的 127.0.0.1 不一定等於 Docker Desktop、遠端 daemon 或容器內部的本機位址。

NO_PROXY 用來列出不經代理的主機或網域，例如本機位址和公司內部網域；不同程式對萬用字元、網域前綴與大小寫環境變數的處理可能不同。設定前請依實際使用的 Docker 版本與作業系統驗證，不要把大量網域一概加入例外，否則必要流量可能繞過預期路徑。

映像檔來源也會影響下載行為。團隊可使用正式登記、權限受控且有維護規範的私有登錄檔；不要為了速度，任意把映像檔改指向不明鏡像站。拉取成功後仍要確認映像檔的來源、標籤或摘要符合專案要求，避免把來源不明的內容帶入建置流程。

若只有 Dockerfile 建置期間下載套件失敗，問題可能出在建置程序，而非 daemon 拉取基礎映像檔的代理。BuildKit 與建置容器的代理傳遞方式，應依 Docker 文件及團隊建置設定處理；不要把含帳密的代理網址寫進 Dockerfile、映像層或建置輸出。將祕密放進 build argument 也不應被當作安全的祕密管理方案。

npm 與 pip：優先維持套件來源可驗證

npm 和 pip 都可透過代理連線，但代理和套件索引是兩個不同設定。若只是連線受限，通常先設定代理並保留團隊覈准的官方或內部索引，比直接改用不熟悉的鏡像來源更容易控管供應鏈風險。替換索引可能影響套件版本、發布延遲、私有套件存取和憑證管理，應先確認專案的鎖定檔、索引規則及組織政策。

npm 可使用設定命令指定 HTTP 代理。此例沿用示範連接埠；如工作環境只需暫時使用，完成後可刪除這兩項設定。

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

npm install

npm config delete proxy
npm config delete https-proxy

若安裝失敗，先以 npm config get proxy 和 npm config get https-proxy 檢查目前值，再確認專案或使用者層級的 .npmrc 是否還有其他設定。不要把存取權杖或代理密碼寫入會提交到版本控制的 .npmrc。若安裝私有套件，依照團隊指定的祕密管理方式提供憑證，並避免在終端機記錄、CI 日誌或錯誤截圖中洩漏。

pip 可在目前終端機以環境變數設定代理，也可透過 pip 支援的設定方式管理。工作階段環境變數較適合先做診斷，關閉終端機後通常不會繼續留存：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

python -m pip install -r requirements.txt

unset HTTP_PROXY
unset HTTPS_PROXY

使用 pip 安裝時，確認執行命令的 Python 環境與預期虛擬環境一致，避免把套件安裝到系統 Python 或另一個專案環境。不要為了排除 TLS 錯誤而加入跳過憑證驗證的參數；應檢查系統憑證、公司覈准的憑證鏈、代理設定及套件索引網址。

• ✅ 優先沿用專案鎖定檔與團隊覈准的套件索引。
• ✅ 將登入權杖、私有索引憑證和代理密碼放入受控祕密管理機制。
• ✅ 安裝後檢查套件版本與解析來源，讓本機和 CI 使用一致的依賴定義。
• ❌ 不要透過關閉 TLS 驗證或使用未知索引來掩蓋連線問題。

動手設定：用一個終端機工作階段逐項驗證

先不要同時修改作業系統、代理用戶端、Git 設定和 Docker 設定。按照下列順序操作，可以判斷故障落在哪一層，也較容易在測試結束後清理暫存值。若電腦由公司管理，請先確認代理、憑證與套件來源是否有指定政策。

1. 確認本地代理資訊。在用戶端設定畫面記下可供應用程式使用的代理協定與連接埠，確認代理服務正在執行。不要沿用其他裝置或舊設定的連接埠。
2. 先測試一般 HTTPS 連線。在同一個終端機確認一般網頁請求能否完成。若一般 HTTPS 已失敗，先檢查本地網路、DNS、代理服務與憑證，不要立刻修改套件索引。
3. 測試 GitHub。以 HTTPS 遠端執行 git ls-remote 或下載熟悉的公開專案。若命令列失敗但瀏覽器正常，檢查 Git 代理與終端機環境變數是否互相覆蓋。
4. 測試 Docker pull。確認 Docker daemon 或 Docker Desktop 的代理設定，再拉取專案允許使用的映像檔。若只有映像檔拉取失敗，檢查 daemon 代理、登錄檔存取及 NO_PROXY，不要只重設 CLI 的環境變數。
5. 測試套件安裝。在正確的虛擬環境或專案目錄中，使用鎖定檔安裝 npm 或 pip 依賴。記錄是 DNS 解析、TLS 憑證、代理拒絕，還是索引回應錯誤，再針對該層處理。
6. 移除臨時設定並再次檢查。清除只供診斷的環境變數和代理值，確認內部服務仍可依預期連線。若需要長期設定，將設定方式記錄在團隊文件，而不是把個人帳密放進專案。

測試時可以記錄工具名稱、作業系統、使用的連線方式、發生時間和錯誤類型，但不要附上訂閱連結、存取權杖、密碼、私有程式碼或含有敏感資訊的完整環境輸出。交給團隊維運人員時，提供可重現的最小步驟，比只回報「下載很慢」更有助於定位問題。

CI 與團隊：避免本機正常、建置環境失敗

CI 執行器通常與開發者電腦隔離，沒有理由假設它能連到開發者本機的 127.0.0.1。在 CI 設定本機迴路位址，實際指向的通常是執行器自身，而不是開發者電腦上的代理程式。若建置需要代理，應由執行環境管理者提供可到達、權限受控的代理服務，並以 CI 的祕密變數傳遞必要憑證。

不同 CI 工作可能分別由 runner、Docker daemon、建置容器或部署容器發出請求。只在 workflow 的 shell 步驟設定環境變數，未必能影響 daemon 拉取基礎映像檔；反過來說，daemon 設定成功也不代表建置容器中的 npm 或 pip 一定能連線。將每一段請求的執行位置寫清楚，才能避免把錯誤修在不相關的層級。

團隊文件宜記錄代理協定、適用範圍、內部網域例外、索引來源、憑證安裝流程和故障回報方式，並說明哪些設定只能用於開發機、哪些也適用於 CI。不要把某位成員的本機代理位址、帳密或帶有個人路徑的設定直接複製到共享建置腳本。環境變數名稱也要依作業系統與工具驗證，不應只因一種大小寫形式在本機生效，就假定所有 runner 都有相同結果。

連線改善還要兼顧合規與安全。代理只負責轉送符合設定的請求，不會自動驗證程式碼來源、套件完整性或帳戶權限；VPN 連線也不會取代企業存取控制、TLS 憑證檢查和程式碼審查。對公共程式碼庫與內部資產採用不同的存取規則，並在調整出口或代理路徑前確認組織政策。