go.mod 是由 Go 工具链自动生成维护的声明式清单，正确初始化只需 go mod init github.com/yourname/yourproject，后续依赖由 go build 或 go mod tidy 自动写入 require；module 是项目唯一导入路径，go 行启用对应版本语言特性，require 列出直接或间接依赖，replace/exclude 仅作临时问题规避，go.mod 与 go.sum 必须一同提交以确保依赖完整性。
go.mod 文件不是“手写”出来的配置文件，而是由 Go 工具链驱动、按需生成和维护的声明式清单——你只需初始化、理解字段含义、在必要时干预，其余交给 go mod tidy 和 go get。
如何正确初始化并让 go.mod 自动生成
别手动新建空 go.mod，也别照抄别人的内容。从零开始的标准流程只有一条命令：
$ go mod init github.com/yourname/yourproject
这个命令会：
• 创建 go.mod，填入 module 和 go 行
• 不添加任何 require（哪怕你代码里已写了 import "github.com/gin-gonic/gin"）
• 后续运行 go build 或 go run 时，Go 才会自动解析导入、下载依赖、并写入 require 条目
常见错误：
• 在 $GOPATH/src 下初始化 → 可能被忽略为 legacy 模式
• 初始化时不带域名路径（如只写 go mod init myapp）→ module 值变成本地目录名，后续被其他项目引用时路径不一致、无法 go get
module / go / require 这三行到底管什么
module 是你的项目“身份证”，不是昵称，是别人 import 你时必须用的完整路径。改它等于换门牌号，所有引用你的代码都得同步改。
go 行不是“最低支持版本”，而是“启用该版本起的模块行为与语言特性”。例如设为 go 1.21，Go 就会启用 embed.FS 的新语义、go.work 支持、以及更严格的 MVS（最小版本选择）规则。升它可能触发编译失败，降它可能让 go mod tidy 拒绝某些依赖。
require 列出的是“我直接或间接需要的模块版本”，但注意：
• 没有 // indirect 标记的，是你代码里 import 了的包
• 有 // indirect 的，是某个依赖的依赖，你没直接 import，但 Go 认为它参与了构建一致性
• 版本号可以是语义化版本（v1.9.1），也可以是伪版本（v0.0.0-20240512103022-abcdef123456），后者常见于未打 tag 的 commit
replace / exclude 不是“高级技巧”，而是问题临时解法
replace 最常用于两种场景：
• 本地调试：把远程模块换成自己改过的本地副本
replace github.com/yourorg/utils => ./internal/utils• 替换不可达源：公司内网私有模块、被墙的代理源
replace golang.org/x/text => github.com/golang/text v0.14.0⚠️ 注意：
replace 不会改变 go.sum 的校验逻辑，只是重定向下载路径；上线前务必删掉，否则 CI 构建会失败
exclude 是兜底手段，不是预防措施。比如某依赖 v2.0.0 引入严重 panic，而你又不能立刻升级到 v2.0.1（因为下游还没适配），才加：
exclude github.com/broken/pkg v2.0.0但它只阻止
go mod tidy 自动选这个版本，不阻止别人手动 go get 它——所以真正安全的做法是配合 require 锁死更低版本
go.mod 和 go.sum 必须一起提交，且不能只信前者
go.mod 说“我要这些依赖”，go.sum 说“这些依赖的内容哈希值是多少”。少了 go.sum，下次 go build 会重新下载并生成新哈希，万一上游悄悄篡改了 zip 包，你就中招了。
容易被忽略的点：
• go.sum 里每行有两个哈希：一个是模块 zip 内容，一个是 go.mod 文件本身（后缀带 /go.mod）
• 如果你 git commit 时漏掉 go.sum，CI 流水线很可能报 verifying signatures 失败
• 不要手动编辑 go.sum；如果校验失败，先 go clean -modcache，再 go mod download
最简验证方式：
$ go mod verify返回空表示一切正常；报错则说明本地缓存或网络中间环节出了问题。
