golang-dependency-management

**角色：**你是 Go 依赖维护者。你将每个新依赖都视为一项长期维护承诺——在使用外部包之前，你会先确认标准库是否已能解决问题。

依赖：

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

Go 依赖管理

AI Agent 规则：添加依赖前先询问

**运行 go get 添加任何新依赖之前，AI Agent 必须征求用户确认。**AI Agent 可能会推荐无人维护、质量低劣或不必要的包，而标准库已经提供了等效功能。使用 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	解释为何需要某个模块或包

Vendor 管理

需要无网络访问的 hermetic 构建、超越校验和的可复现性保证，或要部署到无法访问模块代理的环境时，请使用 go mod vendor。CI 流水线和 Docker 构建有时也会受益于 vendor 管理。每次更改依赖后运行 go mod vendor，并提交 vendor/ 目录。

安装和升级依赖

添加依赖

go get github.com/google/uuid          # Latest version
go get github.com/google/[email protected]   # Specific version
go get github.com/google/uuid@latest   # Explicitly latest
go get github.com/google/uuid@<commit> # Specific commit (pseudo-version)

固定版本之前，请在 pkg.go.dev 上检查模块的可用版本、导入者和已知漏洞 → 参阅 samber/cc-skills-golang@golang-pkg-go-dev 技能。

升级

go get -u ./...            # Upgrade ALL direct+indirect deps to latest minor/patch
go get -u=patch ./...      # Upgrade to latest patch only (safer)
go get github.com/[email protected] # Upgrade specific package

常规更新优先使用 go get -u=patch。Patch 和次要版本更新的风险通常低于主要版本升级，但仍需审核。更新依赖时，请运行：

go get -u=patch ./...
go mod tidy
go test ./...
go vet ./...
govulncheck ./...   # or: go tool govulncheck ./...

涉及持久化、序列化、网络、身份验证、授权、密码学或公共 API 的库，其发布说明和变更日志可能包含有关破坏性变更的重要信息。

移除依赖

go get github.com/google/uuid@none  # Mark for removal
go mod tidy                          # Clean up go.mod and go.sum

安装 CLI 工具

对于 Go 1.24+ 模块，使用 tool 指令在 go.mod 中固定可执行工具。除非模块必须支持 Go <1.24，否则不要创建新的 tools.go 空导入文件。

# Add tools to the current module.
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

# Run pinned tools reproducibly.
go tool golangci-lint run ./...
go tool govulncheck ./...
go tool benchstat old.txt new.txt

# Install all module-pinned tools into GOBIN/PATH when needed.
go install tool

# Update pinned tools deliberately, then review go.mod/go.sum.
go get -u tool
go mod tidy

面向 Go 1.27 或更高版本的模块的 go.mod 结构。这是一个示例目标版本，而非上限；保留项目实际的 go 指令，不要仅为添加工具而更改它。

module example.com/project

go 1.27

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

对于 Go 1.27 或更高版本，go mod tidy 会自动合并重复的 require 块，并强制采用两个块的布局（直接依赖，然后是间接依赖），同时保留现有注释——合并后出现第二个 require 块时，无需手动清理。

仅对于 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 mod init 可能会创建一个带有较旧默认 go 指令的模块。如果项目有意针对较新工具链的 API，请主动更新该指令：

go mod edit -go=1.27
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 文件、何时使用工作区而非单体仓库，以及工作区最佳实践。

• 自动更新依赖项 — 设置 Dependabot 或 Renovate，以自动创建依赖项更新 PR、自动合并策略（何时自动合并，何时要求审核），以及处理安全更新。

• 依赖关系图可视化 — 使用 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 技能，了解经过审核的库推荐

快速参考

# Start a new module
go mod init github.com/user/project

# Add a dependency
go get github.com/google/[email protected]

# Upgrade all deps (patch only, safer)
go get -u=patch ./...

# Remove unused deps
go mod tidy

# Check for vulnerabilities
govulncheck ./...   # or: go tool govulncheck ./...

# Check for outdated deps
go list -u -m -json all | go-mod-outdated -update -direct

# Analyze binary size by dependency
goweight

# Understand why a dep exists
go mod why -m github.com/some/module

# Visualize dependency graph
go mod graph | modgraphviz | dot -Tpng -o deps.png

# Verify checksums
go mod verify