golang-dependency-management

角色設定： 你是一位 Go 相依性管理者。你將每個新的相依性視為長期的維護承諾——在引入外部套件之前，你會先確認標準函式庫是否已經解決了問題。

相依性：

• govulncheck：go install golang.org/x/vuln/cmd/govulncheck@latest

Go 相依性管理

AI 代理程式規則：新增相依性前需先詢問

在執行 go get 新增任何相依性之前，AI 代理程式必須先取得使用者確認。 AI 代理程式可能會建議未維護、低品質或不必要的套件，而這些套件在標準函式庫已提供相同功能時應避免使用。使用 go get -u 升級現有相依性則是安全的。

在建議相依性之前，請評估：

• 標準函式庫是否已涵蓋該使用案例？
• 授權條款是否相容？
• 是否有知名的替代方案？
• 它的功能以及為何需要它？

samber/cc-skills-golang@golang-popular-libraries 技能包含一份經過審查、適合生產環境的函式庫清單。建議優先推薦該清單中的套件。當沒有經過審查的選項時，應優先選擇 Go 團隊（golang.org/x/...）或知名組織的套件，而非冷門的替代方案。

關鍵規則

• go.sum 必須提交——它記錄了每個相依性版本的加密校驗和，讓 go mod verify 能夠偵測供應鏈竄改。沒有它，受污染的代理伺服器可能悄悄替換惡意程式碼
• 每次發行前執行 govulncheck ./... 或 go tool govulncheck ./...——在已知 CVE 進入生產環境前加以攔截
• 新增相依性前，維護狀態、授權相容性以及標準函式庫替代方案都是重要的考量——每個相依性都會增加攻擊面、維護負擔和二進位檔大小
• 每次變更相依性前執行 go mod tidy——移除未使用的模組並加入遺漏的模組，保持 go.mod 的正確性

go.mod 與 go.sum

基本指令

指令	用途
go mod tidy	加入遺漏的相依性，移除未使用的相依性
go mod download	將模組下載到本機快取
go mod verify	驗證快取的模組是否符合 go.sum 校驗和
go mod vendor	將相依性複製到 vendor/ 目錄
go mod edit	以程式方式編輯 go.mod（腳本、CI）
go mod graph	印出模組需求圖
go mod why	解釋為何需要某個模組或套件

Vendoring

當你需要封閉建置（無網路存取）、超越校驗和的可重複性保證，或部署到沒有模組代理存取的環境時，請使用 go mod vendor。CI 管線和 Docker 建置有時會受益於 vendoring。在每次相依性變更後執行 go mod vendor，並提交 vendor/ 目錄。

安裝與升級相依性

新增相依性

go get github.com/google/uuid          # 最新版本
go get github.com/google/uuid@v1.6.0   # 特定版本
go get github.com/google/uuid@latest   # 明確指定最新版
go get github.com/google/uuid@<commit> # 特定提交（偽版本）

在鎖定版本之前，請在 pkg.go.dev 上檢查該模組的可用版本、匯入者以及已知漏洞 → 參閱 samber/cc-skills-golang@golang-pkg-go-dev 技能。

升級

go get -u ./...            # 將所有直接與間接相依性升級到最新的次要或修補版本
go get -u=patch ./...      # 僅升級到最新的修補版本（較安全）
go get github.com/pkg@v1.5 # 升級特定套件

例行更新建議使用 go get -u=patch。修補和次要更新通常風險低於主要升級，但仍需審查。進行相依性更新時，請執行：

go get -u=patch ./...
go mod tidy
go test ./...
go vet ./...
govulncheck ./...   # 或：go tool govulncheck ./...

對於影響持久化、序列化、網路、認證、授權、加密或公開 API 的函式庫，其發行說明和變更日誌可能包含關於重大變更的重要資訊。

移除相依性

go get github.com/google/uuid@none  # 標記為移除
go mod tidy                          # 清理 go.mod 和 go.sum

安裝 CLI 工具

對於 Go 1.24+ 模組，使用 tool 指令將可執行工具固定在 go.mod 中。除非模組必須支援 Go <1.24，否則不要建立新的 tools.go 空白匯入檔案。

# 將工具加入目前模組。
go get -tool github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
go get -tool golang.org/x/vuln/cmd/govulncheck@latest
go get -tool golang.org/x/perf/cmd/benchstat@latest

# 可重複地執行已固定的工具。
go tool golangci-lint run ./...
go tool govulncheck ./...
go tool benchstat old.txt new.txt

# 在需要時將所有模組固定的工具安裝到 GOBIN/PATH。
go install tool

# 審慎地更新已固定的工具，然後審查 go.mod/go.sum。
go get -u tool
go mod tidy

針對目標為 Go 1.26 或更新版本的模組，go.mod 的形狀如下。這只是範例目標，並非上限；請保留專案實際的 go 指令，不要為了加入工具而變更它。

module example.com/project

go 1.26

tool (
    github.com/golangci/golangci-lint/v2/cmd/golangci-lint
    golang.org/x/vuln/cmd/govulncheck
    golang.org/x/perf/cmd/benchstat
)

僅針對 Go <1.24，使用舊式的 tools.go 空白匯入解決方案：

//go:build tools

package tools

import (
    _ "github.com/golangci/golangci-lint/v2/cmd/golangci-lint"
    _ "golang.org/x/vuln/cmd/govulncheck"
)

規則：Go 1.24+ 使用 tool 指令。Go <1.24 使用 tools.go 作為備案。

Go 1.26+ 模組目標注意事項

使用 Go 1.26 或更新版本的 toolchain 時，go mod init 可能會建立一個使用較舊預設 go 指令的模組。如果專案有意以 Go 1.26+ API 為目標，請審慎更新該指令：

go mod edit -go=1.26
go mod tidy

對於未來的 Go 版本，請使用專案預期的目標版本。在專案明確同意升級之前，不要使用比模組 go 指令更新的 API。

深入探討

• 版本控制與 MVS — 語意化版本規則（major.minor.patch）、何時遞增每個數字、預發行版本、最小版本選擇（MVS）演算法（為什麼你不能直接選「最新版」），以及主要版本後綴慣例（v0、v1、v2 後綴用於重大變更）。

• 稽核相依性 — 使用 govulncheck 進行漏洞掃描、追蹤過時相依性、分析哪些相依性導致二進位檔過大（goweight），以及區分僅測試相依性與二進位檔相依性，以保持 go.mod 整潔。

• 相依性衝突與解決 — 診斷版本衝突（當你請求不相容版本時 go get 的行為）、解決策略（用於本機開發的 replace 指令、用於損壞版本的 exclude、用於應跳過的已發行版本的 retract），以及跨相依性樹的衝突處理流程。

• Go 工作區 — 用於多模組開發的 go.work 檔案（例如函式庫 + 範例應用程式）、何時使用工作區 vs 單一儲存庫，以及工作區最佳實務。

• 自動化相依性更新 — 設定 Dependabot 或 Renovate 以自動產生相依性更新 PR、自動合併策略（何時自動合併 vs 需要審查），以及處理安全性更新。

• 視覺化相依性圖 — 使用 go mod graph 檢查完整相依性樹、使用 modgraphviz 將其視覺化，以及使用互動式工具找出哪些相依性鏈導致膨脹。

交叉參考

• → 參閱 samber/cc-skills-golang@golang-continuous-integration 技能以了解 Dependabot/Renovate CI 設定
• → 參閱 samber/cc-skills-golang@golang-security 技能以了解使用 govulncheck 進行漏洞掃描
• → 參閱 samber/cc-skills-golang@golang-popular-libraries 技能以了解經過審查的函式庫建議

快速參考

# 啟動新模組
go mod init github.com/user/project

# 新增相依性
go get github.com/google/uuid@v1.6.0

# 升級所有相依性（僅修補版本，較安全）
go get -u=patch ./...

# 移除未使用的相依性
go mod tidy

# 檢查漏洞
govulncheck ./...   # 或：go tool govulncheck ./...

# 檢查過時相依性
go list -u -m -json all | go-mod-outdated -update -direct

# 按相依性分析二進位檔大小
goweight

# 了解某個相依性存在的原因
go mod why -m github.com/some/module

# 視覺化相依性圖
go mod graph | modgraphviz | dot -Tpng -o deps.png

# 驗證校驗和
go mod verify