go.mod 是 Go 模块的权威声明，定义模块路径、Go 版本及直接依赖版本；module 声明导入路径，go 指定语言版本，require 列出直接依赖；replace 用于临时替换依赖，exclude 用于排除特定版本；go.sum 校验依赖完整性；indirect 表示间接依赖。
go.mod 文件不是配置文件，而是 Go 模块的**权威声明**——它定义了当前模块的路径、Go 版本要求，以及所有直接依赖的精确版本。只要 go.mod 存在且合法，go build、go run 等命令就完全绕过 GOPATH，按此文件解析依赖树。
go.mod 的三要素：module、go、require 是什么角色
module 声明当前模块的导入路径（如 github.com/user/project），必须唯一且与代码实际可被 import 的路径一致；go 指定该模块默认使用的 Go 语言版本（影响泛型、切片操作等语法可用性）；require 列出所有**直接依赖**及其版本（含伪版本 v1.2.3-20220101000000-abcdef123456）。
常见错误现象：go run . 报错 cannot find module providing package ...，往往是因为 module 路径写错，或当前目录不在模块根下（即没有 go.mod 文件的目录里执行命令）。
-
module路径不能是本地路径（如./mylib），也不能省略域名（如myproject） -
go 1.19不代表强制升级 Go，但若用了~版本比较符或any类型，低于该版本会报错 -
require中的版本号一旦写死（如v1.8.0），go get不会自动升级，除非显式调用go get -u
replace 和 exclude 怎么用，什么时候该用
replace 用于临时替换某个依赖模块的源（比如本地调试、fork 后未发版、私有仓库），它优先级高于 require；exclude 则彻底从构建中移除某版本（常用于规避已知 panic 的特定补丁版本）。
立即学习“go语言免费学习笔记（深入）”；
使用场景举例：你依赖的 github.com/some/lib 在 v2.1.0 有内存泄漏，但官方尚未发布修复版，而你在 fork 的 v2.1.1-fix 分支已修复 —— 此时可用 replace 指向你的 fork。
-
replace github.com/some/lib => ./local-fix：指向本地目录，路径必须存在且含有效go.mod -
replace github.com/some/lib => github.com/yourname/lib v2.1.1-fix：指向远程 fork 的 tag 或 commit -
exclude github.com/some/lib v2.1.0：仅当该版本被间接引入时才跳过；对直接require的版本无效 -
exclude不解决依赖冲突，只是“掩耳盗铃”；真正要解冲突得靠go mod graph定位源头
go.sum 是什么，删掉它会怎样
go.sum 是模块下载内容的校验和快照，每行格式为 go build 默认校验它——若下载的 zip 内容哈希不匹配，会拒绝构建并报错 checksum mismatch。
删掉 go.sum 不影响编译，但下次 go mod download 或 go build 会重新生成它；如果网络环境不可信（比如代理篡改包），缺失 go.sum 就失去完整性保护。
- CI 环境务必保留
go.sum并提交进 Git，否则不同机器可能拉到被污染的依赖 -
go mod verify可手动校验所有已下载模块是否匹配go.sum - 若因换源导致哈希不一致（如 GOPROXY=direct vs proxy.golang.org），应先
go clean -modcache再重试
为什么 go mod tidy 有时会加一堆 indirect 依赖
indirect 标记出现在 require 行末尾，表示该模块**不是你直接 import 的，而是某个直接依赖的依赖**。它通常在以下情况出现：go.mod 旧、依赖链升级、或你删了某 import 但没运行 go mod tidy。
这不是 bug，而是 Go 模块系统“最小显式依赖”的体现：只有当某个 indirect 模块被你的代码直接 import 时，它才会升为非 indirect；反之，若你删了 import，它也不会自动消失，需 go mod tidy 清理。
-
go mod tidy -v会输出哪些包被添加/删除，方便确认是否合理 - 若发现某个
indirect模块版本异常高（如v0.0.0-20200101000000-000000000000），大概率是上游未打 tag，应检查其go.mod是否规范 - 不要手动编辑
go.mod删除indirect行——go mod tidy才是唯一可信的维护方式
go.mod 的核心约束力来自 Go 工具链本身，而非开发者约定；任何绕过 go mod 手动管理 vendor 或 patch 依赖的行为，都会在 go list -m all 或 go mod graph 里立刻暴露不一致。最易被忽略的是：module 路径变更后，旧 import 语句不会自动更新，必须同步修改代码里的 import 声明，否则编译失败。
