go mod download 的瓶頸常在跨境延遲、GOPROXY 鏈與 GOSUMDB 政策是否一致。本文以決策矩陣對照「自建模組代理」與「公共代理鏈」，並列出 GOPRIVATE、GONOPROXY、GOSUMDB、GONOSUMDB、GOMODCACHE 等可執行參數。延伸：Python uv／PyPI 矩陣、Rust Cargo 矩陣、技術部落格。
① 決策矩陣：自建模組代理 vs 公共 GOPROXY 鏈
是否部署 Athens／制品庫前置，是治理成本與快取命中的取捨。公共鏈（逗號分隔端點＋direct）上手快；若有內網模組、審計或離線構建，應把自建代理放鏈首，再接核准的公共鏡像二級回源。
| 方案 | 最適場景 | 維運與風險 | GOPROXY 鏈建議形態 |
|---|---|---|---|
| 公共代理鏈 | 以開源模組為主、無內網倉、想快速在 CI 落地 | 依賴第三方 SLA；跨境仍可能抖動；需信任 sumdb 路徑 | 鏡像A,鏡像B,direct（鏡像請替換為組織核准域名） |
| 自建模組代理（如 Athens） | 多專案共用快取、要審計出站、需固定「可重現拉取」 | 需儲存、監控、清理與權限；但可顯著降低對外突發流量 | https://athens.corp.internal,鏡像,direct |
| 混合 | 內外模組並存、CI 與筆電策略要一致 | 以 GOPRIVATE 路由切開公開／私有抓取邏輯最穩 | 私有域名走 VCS 直連或內部代理；公開走鏈式回源 |
判斷：大量 job 重複拉相同版本且 RTT 高 → 評估自建／托管代理；構建頻率低 → 先把 GOPROXY 鏈與 GOMODCACHE 持久化做對。
② 環境變數參數清單（可複製到 shell／CI）
下表為常見 Go 模組環境變數；域名請替換為實際值，勿在日誌洩漏含令牌的代理 URL。
| 變數 | 典型設定示例 | 作用與注意 |
|---|---|---|
GOPROXY | https://proxy.example,https://proxy.golang.org,direct | 逗號分隔鏈式回源：前者失敗或缺包才往後走；末尾 direct 建議保留（法遵限制除外） |
GOPRIVATE | *.corp.example,github.com/myorg/* | 匹配前綴視為私有：不對外廣播、預設不走公開 sumdb／代理行為與公開模組不同 |
GONOPROXY | 常與 GOPRIVATE 相同或更細 | 明確指定「不要走 GOPROXY」的模組前綴；用於內網直連 Git／HTTP |
GOSUMDB | sum.golang.org 或企業 sumdb URL | checksum 資料庫端點；內網需配套鏡像或代理，避免 CI 無法出網 |
GONOSUMDB | *.corp.example | 對匹配模組略過 sumdb；僅在資安與供應鏈流程可替代校驗時使用 |
GOMODCACHE | 如 $HOME/go/pkg/mod-ci | 固定模組快取目錄，便於掛卷、預熱與清理腳本對齊 |
GOFLAGS | -mod=readonly | CI 建議開啟，避免編譯步悄悄改 go.mod；更新依賴應在獨立 job 執行 |
GOPATH | （可選）自訂 workspace 根 | 與 GOMODCACHE 預設位置相關；多版本 toolchain 並存時建議文件化路徑 |
③ 鏈式回源與 GOSUMDB：弱網與企業網路下的組態要點
鏈序即策略：越靠前代表「優先命中快取」；中間層宜放區域可達的鏡像，最後才 direct 打上游 VCS／proxy.golang.org，避免每次冷啟動都跨境握手。
私有模組三件套：GOPRIVATE＋（視需要）GONOPROXY＋GONOSUMDB；並確保遠端 Mac 上 git config／.netrc／SSH key 與 CI 秘密一致，否則會誤判成「代理壞了」。
TLS／代理：HTTPS 攔截環境須信任企業根 CA；HTTPS_PROXY 與 NO_PROXY 要涵蓋內網，避免 zip 與 sumdb 分流失敗。
# 遠端 Mac 或 CI job（bash／zsh）— 示例域名請替換
export GOPRIVATE="*.corp.example,github.com/myorg/private-*"
export GONOPROXY="$GOPRIVATE"
export GONOSUMDB="$GOPRIVATE"
export GOPROXY="https://athens.corp.example,https://proxy.golang.org,direct"
export GOSUMDB="sum.golang.org"
export GOMODCACHE="${GOMODCACHE:-$HOME/go/pkg/mod-ci}"
export GOFLAGS="${GOFLAGS:--mod=readonly}"
go env -w GOPROXY="$GOPROXY" GOSUMDB="$GOSUMDB" 2>/dev/null || true
go mod download -x
go env -w 會寫入使用者設定；共享 runner 建議只用 CI 環境變數注入。
④ CI 快取與預拉：讓遠端節點重複構建「少打外網」
將 GOMODCACHE 納入快取鍵（如 go.sum 雜湊），編譯前獨立跑 go mod download 可縮小重試範圍；GOFLAGS=-mod=readonly 避免測試 job 改寫模組圖。多語言流水線可對齊OpenClaw 依賴同步自動化。
# 建議：單獨 cache 步（示例） mkdir -p "$GOMODCACHE" go mod download # 後續構建步沿用相同 GOMODCACHE 與 GOFLAGS
⑤ 簡短 FAQ
不建議在一般 CI 關閉 checksum 驗證；若政策要求，應以資安核准的流程改走企業 sumdb 或鎖定可信代理產物，而不是全域 off。
常見實作在「找不到版本」時會試下一端點；TLS／逾時應靠重試與前段穩定快取，不宜無限加鏈。