go.mod 是现代 Go 项目必需的模块声明文件；需用 go mod init 正确初始化 module path；go.sum 不可手动编辑，是安全校验契约；replace 和 exclude 为临时手段，有风险；go mod tidy 同步依赖关系而非清理冗余。
go.mod 是 Go 模块系统的基石，不是可选配置，而是现代 Go 项目必须存在的声明文件；没有它，go build、go test 等命令在模块感知模式下会拒绝工作或降级为 GOPATH 模式（已废弃）。
如何初始化一个新模块并设置正确的 module path
在项目根目录执行 go mod init example.com/myapp，其中 example.com/myapp 是你的模块路径（module path），它应与代码未来可能被 import 的路径一致。常见错误包括：
- 用本地路径如
go mod init ./src或go mod init myapp—— 这会导致后续go get无法解析依赖，且他人无法正确导入你的包 - 模块路径含大写字母或下划线（如
MyApp_v1）—— Go 官方不推荐，部分工具链（如go list -m all）可能异常 - 未提前规划域名归属：若使用
github.com/username/repo，请确保该路径真实存在且你有写权限，否则go get会失败
为什么 go.sum 不该手动编辑，以及何时需要重生成
go.sum 是模块校验和文件，记录每个依赖模块的哈希值，用于防止依赖篡改。它由 Go 工具链自动生成和维护，手动修改会导致 go build 报错 checksum mismatch。
- 当你执行
go get、go mod tidy或首次go build时，Go 自动更新go.sum - 若因网络问题导致
go.sum中某行缺失或损坏，不要删掉整行，而应运行go mod download -dirty或临时设置GOPROXY=direct后再go mod tidy - 团队协作中，
go.sum必须提交进 Git —— 它不是“缓存”，而是安全契约的一部分
replace 和 exclude 的典型使用场景与风险
replace 用于临时覆盖依赖路径（如本地调试、fork 修复），exclude 则强制忽略某个版本（极少用，仅限已知严重 bug 且无替代方案）。
立即学习“go语言免费学习笔记（深入）”；
-
replace github.com/some/lib => ./local-fix：路径必须是绝对或相对（从go.mod所在目录起算），且目标目录需含有效的go.mod -
replace不影响go list -m all输出的模块列表，但会影响实际编译时加载的代码；上线前务必移除，否则 CI 构建可能失败 -
exclude仅对当前模块生效，无法传递给下游依赖；过度使用会导致go mod graph出现断裂，难以排查版本冲突 - 替代
exclude的更安全做法是用go get github.com/some/lib@v1.2.3显式降级
go mod tidy 的真实作用与常见误用
go mod tidy 并非“清理冗余依赖”，而是同步 go.mod 与当前代码中实际 import 的模块关系：添加缺失的 require、删除未使用的 require、更新 indirect 标记。
- 它不会自动升级次要版本（如从 v1.2.0 → v1.3.0），除非你显式
go get -u - 执行前确保所有
.go文件已保存，否则可能漏掉新增的 import 导致误删依赖 - 在 CI 中建议加
-v参数（go mod tidy -v）观察变更，避免静默修改go.mod引发合并冲突 - 若项目含多个
main包（如 cmd/ 下多个二进制），需在每个子目录分别运行go mod tidy，或在根目录用go mod tidy -compat=1.21（视 Go 版本而定）确保兼容性
模块路径设计、go.sum 的不可变性、replace 的临时性，这三者最容易在跨团队或长期维护项目中被忽略——它们不报错，但会在某次 go get 或 CI 构建时突然暴露。
