5.3 依赖管理：外部供应商名单

5.3 依赖管理：外部供应商名单

本节摘要：go.mod 是项目的供应商名单，go.sum 是验货回执。本节讲清模块机制的核心文件、五个高频操作、版本与替换策略，以及供应链安全的最小依赖哲学。读完本节，任何一台机器上都能复现出完全相同的构建，升级依赖也从开盲盒变成走流程。

上一节的测试给了改动底气，但底气有边界：改动自己的代码是可控的，依赖的第三方库升级是另一回事。把依赖比作供应商名单很贴切——进什么货、哪个批次、验没验过，都要有账可查。Go 的 module 机制就是这套账本，本节带你把它用熟。

两份档案：go.mod 与 go.sum

项目根目录的 go.mod 记录三件事：模块身份、语言版本、依赖清单；go.sum 记录每个依赖内容的哈希，是"货没被调包"的回执：

module shiftcenter

go 1.22

require (
	github.com/pkg/errors v0.9.1
	golang.org/x/sync v0.6.0
)
​

依赖分直接与间接两类，缩进的是间接依赖。多数时候你不需要手工编辑这个文件——命令行工具会替你维护。go.sum 只增不减地积累验货记录，随代码一起提交，CI 与同事的机器据此验货，构建才可复现。

日常五操作

$ go mod tidy          # 对账：按 import 补齐缺失、清掉未用
$ go get golang.org/x/sync@v0.7.0   # 指定版本进货或升级
$ go get -u ./...      # 全部直接依赖升到最新次版本
$ go get golang.org/x/sync@v0.6.0   # 回退：写旧版本号即可
$ go mod verify        # 验货：核对本地缓存与哈希
​

tidy 是最高频的一条，提交前跑一遍能保持账实相符。get 的版本后缀很灵活：@latest 取最新，@v1.2.3 定点，@e3702fa 提交哈希进某个未发布修复。这些命令覆盖日常九成场景，剩下的一成（替换、排除）见下文。

依赖冻结与可复现构建

可复现构建的最后一环是构建环境本身的锁定：语言版本由 go.mod 的版本声明加工具链管理机制约束，依赖版本由 go.mod 与 go.sum 锁定，剩下的是构建脚本的参数统一。三样齐了，任何人在任何机器上构建出的产物逐字节一致，"我这里没问题"式的争论失去土壤。发布产物上用版本信息命令记录构建来源，事故时能把线上二进制精确对应到某次提交。

冻结的另一面是解冻节奏：依赖不是越旧越稳，长期不升级的名单会在某天被迫一次性跨越多个版本，风险集中爆发。稳妥的节奏是周期性小升级——每月或每双周把补丁版本跟齐，季度处理次版本，让每次变更都足够小、可回滚、可归因。供应链安全审计也在这个节奏里顺路完成。

版本语义与两条特殊规则

Go 遵循语义化版本：主版本变更允许破坏兼容。由此有两条新手必知的规则：主版本大于等于二时，模块路径要带后缀（如 /v2），对调用方而言它是一个完全不同的新模块，新旧版本可以同时共存于一次构建中——这让破坏性升级从"全量切换"变成"逐包迁移"。未发布代码则用伪版本引用，形如 v0.0.0-时间戳-哈希，修复上游紧急缺陷时很有用。

本地开发还有一个利器 replace：把某个依赖指到本地目录调试，提交前再移除或放进独立的工作区配置：

require github.com/pkg/errors v0.9.1

replace github.com/pkg/errors => ../local-errors   # 调试用，慎入主分支
​

replace 双向都能用——也能钉死一个有问题的次版本，等上游修复再解开。团队协作里建议把它隔离在个人工作区文件中，避免污染公共账本。

供应链安全：少即是稳

每个依赖都是供应链上的一环，安全策略就一句：名单越短，风险越小。三条实操纪律：

• 引入依赖前问一遍"标准库加五十行能不能实现"，能用标准库就不引第三方，Go 标准库覆盖面远超一般预期。
• 用官方漏洞审计工具定期扫名单，高危项排期升级；审计纳入 CI 定时任务，而不是想起来才跑。
• 版本升级走小步：先升开发环境观察，再灰度生产；大版本升级单独立项，不与功能发布混车。

公司内网与私有模块

企业场景绕不开两个问题：公司内部的私有库怎么被引用，公网模块的下载怎么又快又稳。

私有模块的引用没有特殊语法，普通 get 即可，关键在告诉工具链"这些路径别走公共代理"：用环境变量把公司域名段设为私有标记，工具链会绕过公共代理直接走版本库拉取，鉴权交给 git 凭据。误把私有路径交给公共代理，轻则拉取失败，重则内部模块名外泄，这条配置在入职第一天就该配好。

公网下载的稳定性由模块代理与校验和数据库解决：代理缓存全球公开模块，拉取快且不受源站波动影响；校验和数据库记录每个版本的全球共识哈希，配合本地 go.sum 双重防篡改。团队内网自建一层代理镜像，是中大型团队的标准动作。

$ go env GOPRIVATE GOPROXY
git.example.com
https://proxy.golang.cn,direct
$ go mod vendor   # 极少数强离线场景：把依赖复制进项目内 vendor 目录
​

vendor 目录是最后手段：它把依赖源码复制进仓库，构建完全不依赖网络与代理。代价是仓库体积膨胀、依赖更新变成显式提交，只建议在强隔离环境（涉密内网、交付介质）使用。常规项目保持"名单加回执"模式即可，vendor 与 replace 一样，用了就要在团队约定里写明启用范围。

完整案例：一次破坏性升级的走法

背景：项目依赖的配置库发布了大版本，旧版本不再维护，且新版本修复了一个配置热加载的并发缺陷——正是 4.2 里同类问题的修复，不升不行。

操作：五步走。读迁移指南，列出破坏点（构造函数签名变更、弃用两个导出函数）；建立升级分支，get 指定新主版本路径；按迁移指南逐点修改，每改一个包跑一遍全量测试与竞态检测；基准测试确认热加载路径无性能回退；灰度环境观察一天后合入。

结果：升级合入，热加载缺陷随之修复，全量测试与竞态检测通过，性能基准持平。

解读：这次升级顺利的关键在测试——5.2 的验收制度在这里兑现：没有那套测试，破坏性升级的每一步都是裸奔。另一个关键是大版本共存机制：迁移可以按包逐步进行，新旧配置库在同一次构建里过渡，不存在"必须一次全切"的悬崖。

变式：如果上游迟迟不发修复版本，可以临时用 fork：replace 指向你维护的分支，同时向上游提交修复，合并发布后撤掉 replace 回到官方版本。fork 是止血带不是器官——挂着它的时间越长，偏离上游越远，后续升级越贵。

收班要点

• go.mod 是名单、go.sum 是回执，两者都提交，构建才可复现。
• 五操作覆盖日常：tidy 对账、get 进货升级回退、verify 验货。
• 大版本带路径后缀，新旧共存逐包迁移；replace 调试好用但别进主分支。
• 供应链三纪律：依赖最小化、漏洞审计常态化、升级小步走。
• 升级的底气来自上一节的测试体系，工程环节环环相扣。

名单管清了，下一节走最后一道工序：把构建产物部署上线，并让它在凌晨也能体面地值班与退休。