在 Go 项目中添加、升级、审计依赖时如何管理…

适用于 Go 项目新增/移除/升级依赖、解决版本冲突、审计依赖树漏洞与体积、使用 vendoring、tool 指令和 go.work 工作区的场景。

适用场景

解决思路

1. 添加任何新依赖前，AI agent 必须先向用户确认；评估标准包括：标准库是否已覆盖该用例、许可证是否兼容、是否有知名替代品、该包做什么以及为何需要。升级已有依赖（go get -u）无需确认。
2. 优先推荐经过审核的生产级库（参考 samber/cc-skills-golang@golang-popular-libraries 列表）；无审核选项时，优先选择 Go 团队（golang.org/x/...）或知名组织的包，而非冷门替代品。
3. 必须提交 go.sum，它记录每个依赖版本的加密校验和，使 go mod verify 能检测供应链篡改；否则被攻陷的代理可静默替换恶意代码。
4. 每次发布前运行 govulncheck ./... 或 go tool govulncheck ./...，在进入生产前捕获依赖树中的已知 CVE。
5. 每次改动依赖的提交前运行 go mod tidy，移除未使用模块并补全缺失模块，保持 go.mod 诚实。
6. 掌握核心命令：go mod tidy（增删依赖）、go mod download（下载到本地缓存）、go mod verify（校验缓存模块与 go.sum 校验和一致）、go mod vendor（复制依赖到 vendor/）、go mod edit（脚本/CI 中以编程方式编辑 go.mod）、go mod graph（打印模块需求图）、go mod why（解释某模块或包为何被需要）。
7. 需要封闭构建（无网络访问）、超出校验和的可复现性保证，或部署到无模块代理访问的环境时使用 go mod vendor；任何依赖变更后运行 go mod vendor 并提交 vendor/ 目录。
8. 添加依赖：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>（指定提交，伪版本）。
9. 固定版本前，在 pkg.go.dev 上检查该模块的可用版本、导入方和已知漏洞（参考 samber/cc-skills-golang@golang-pkg-go-dev）。
10. 升级依赖：go get -u ./...（升级所有直接+间接依赖到最新 minor/patch）、go get -u=patch ./...（仅升级到最新 patch，更安全）、go get github.com/pkg@v1.5（升级特定包）。日常更新优先用 go get -u=patch。
11. 依赖更新流程：go get -u=patch ./... → go mod tidy → go test ./... → go vet ./... → govulncheck ./...（或 go tool govulncheck ./...）。
12. 阅读影响持久化、序列化、网络、认证、授权、加密或公共 API 的库的发布说明和变更日志，其中可能包含破坏性变更的重要信息。
13. 移除依赖：go get github.com/google/uuid@none 标记移除，再 go mod tidy 清理 go.mod 和 go.sum。
14. Go 1.24+ 模块用 go.mod 中的 tool 指令固定可执行工具，不要新建 tools.go 空导入文件（除非模块必须支持 Go <1.24）。添加工具：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。
15. 可复现地运行固定工具：go tool golangci-lint run ./...、go tool govulncheck ./...、go tool benchstat old.txt new.txt；需要时用 go install tool 将所有模块固定工具安装到 GOBIN/PATH；用 go get -u tool 更新固定工具后审查 go.mod/go.sum。
16. go.mod 中 tool 指令的形态示例：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 指令，不要仅为添加工具而修改它。
17. Go 1.27+ 中 go mod tidy 会自动合并重复的 require 块并强制两块布局（先直接依赖、后间接依赖），保留已有注释，合并引入第二个 require 块后无需手动清理。
18. 仅 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。
19. 使用较新工具链时，go mod init 可能生成带较旧默认 go 指令的模块；若项目有意面向较新工具链的 API，需有意更新指令：go mod edit -go=1.27 然后 go mod tidy。在项目明确同意升级前，不要使用比模块 go 指令更新的 API。
20. 深入主题参考：版本与 MVS（语义化版本规则、预发布版本、最小版本选择算法、v0/v1/v2 主版本后缀约定）；依赖审计（govulncheck 漏洞扫描、跟踪过期依赖、用 goweight 分析哪些依赖使二进制变大、区分仅测试依赖与二进制依赖）；依赖冲突与解决（诊断版本冲突、用 replace 做本地开发、用 exclude 排除损坏版本、用 retract 撤回已发布版本）；Go 工作区（go.work 多模块开发、工作区 vs 单仓、最佳实践）；自动化依赖更新（Dependabot/Renovate、自动合并策略、安全更新处理）；依赖图可视化（go mod graph、modgraphviz、交互式工具查找导致臃肿的依赖链）。
21. 快速参考命令：go mod init github.com/user/project（新建模块）、go get github.com/google/uuid@v1.6.0（添加依赖）、go get -u=patch ./...（仅升级 patch，更安全）、go mod tidy（移除未使用依赖）、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（校验校验和）。

适用边界 · 注意事项

• 不要用于修复代码中可利用的漏洞（应参考 samber/cc-skills-golang@golang-security 技能）。
• 不要用于将 Dependabot/Renovate 更新机器人接入 CI 工作流（应参考 samber/cc-skills-golang@golang-continuous-integration 技能）。