go mod download 不记录依赖关系，只将 go.mod 中声明的模块下载到本地缓存；go.mod 是唯一权威依赖声明文件，go.sum 仅存储校验和快照，真正的依赖同步必须由 go mod tidy 完成——它扫描 import、增删 require、更新 go.sum。
go mod download 会记录什么，go.sum 和 go.mod 哪个管同步
go mod download 本身不“记录”依赖下载行为——它只是把 go.mod 中声明的模块版本拉到本地缓存（$GOPATH/pkg/mod/cache），不修改任何项目文件。真正参与“同步”的是 go.mod（声明依赖树）和 go.sum（校验和快照）。其中 go.sum 是只读快照，不能靠它反向还原依赖；而 go.mod 才是唯一权威来源。
用 go mod tidy 实现真正的依赖对齐
所谓“一键同步下载记录”，本质是让本地模块状态与 go.mod 完全一致：已下载、已校验、无残留。这一步必须用 go mod tidy，不是 go get 或 go mod download。
-
go mod tidy会读取所有.go文件中的 import，对比go.mod，自动添加缺失项、删除未引用项，并触发对应模块下载和go.sum更新 - 执行前确保当前目录是 module 根（有
go.mod），且GO111MODULE=on（Go 1.16+ 默认开启） - 如果想跳过测试文件里的 import，加
-compat=1.21等参数不影响行为，但-v可看具体下载动作 - 注意：它会改写
go.mod和go.sum，建议先git diff确认变更意图
为什么 go mod download 不适合“同步记录”
go mod download 只做一件事：按 go.mod 把所有依赖（含间接依赖）下到本地缓存，不检查代码里是否真用到了，也不清理没被引用的模块。它产生的“记录”只是缓存存在性，无法反映项目真实依赖关系。
- 常见误用：CI 中先
go mod download再go build，结果构建失败——因为go.mod里漏了某 indirect 依赖，或go.sum校验失败 - 它不会更新
go.sum中缺失的 checksum 行，也不会剔除已不用的模块条目 - 多模块 repo 中，每个子模块需单独进目录运行，不能靠一次命令全局同步
CI/CD 中推荐的一键流程
在 GitHub Actions、GitLab CI 等场景下，“同步依赖”目标其实是保证构建可重现。最简可靠路径是：
- 先
go mod download -x（加-x查看实际 fetch 日志，便于排错） - 再
go mod tidy -v（强制对齐并输出操作详情） - 最后
go list -m all | wc -l（快速确认模块总数，用于前后比对） - 关键：整个过程必须在 clean 环境（如全新 container）中执行，避免复用旧缓存导致状态漂移
缓存 $GOPATH/pkg/mod 目录能加速，但不能替代 tidy —— 因为 checksum、require 版本、indirect 标记这些元信息只存在于 go.mod/go.sum，不在缓存文件名里。
