go mod 是 Go 1.11+ 唯一官方依赖管理机制，必须用 URL 格式显式初始化（如 go mod init github.com/user/proj），require 不支持 ^/~ 版本符号，go mod tidy 按 import 自动同步依赖，go.sum 保障校验完整性。
go mod 是 Go 项目依赖管理的事实标准，不是可选项——只要项目用到了第三方包或需要跨目录组织代码，就必须启用模块化。不初始化 go mod，go build 和 go run 会退回到旧的 GOPATH 模式，导致依赖不可控、版本漂移、CI 构建失败。
go mod init 必须在项目根目录执行，且模块路径不能随意写
模块路径（module path）不是随便起的名字，它本质是未来别人 go get 你这个库时的导入路径。比如你想让别人用 import "github.com/yourname/myapp"，那初始化就得写：go mod init github.com/yourname/myapp。
如果错写成 go mod init myapp，后续发布到 GitHub 后，别人 go get 会拉错路径，而且 go list -m 显示的模块名也会不一致，影响工具链识别。
常见错误现象：
• go build 报错 cannot find module providing package ...
• go get 成功但实际没更新 go.mod 中的版本
• IDE（如 VS Code）提示找不到包，但命令行能编译通过
- 模块路径必须与代码托管地址匹配（如 GitHub、GitLab），否则私有仓库或企业内网场景下
go get会失败 - 本地开发调试时，可用伪版本（如
v0.0.0-20260714135700-abc123）替代未打 tag 的提交，但上线前应打正式语义化 tag - 若项目暂无远程仓库，也建议用占位路径（如
example.com/myproj），避免后期迁移成本
go mod tidy 不只是“整理依赖”，它会强制校验所有 import 路径
go mod tidy 的核心动作是：扫描全部 .go 文件中的 import 语句，补全缺失的 require，移除未被引用的依赖，并同步更新 go.sum。它不看代码逻辑是否运行，只认 import 是否存在。
容易踩的坑：
• 误删了某个 import 但没运行 go mod tidy，go build 仍能过（因为缓存还在），但 CI 环境会失败
• 在 internal/ 目录下写了临时测试代码并 import 了 dev-only 包（如 github.com/go-delve/delve），go mod tidy 会把它加进 go.mod，污染生产依赖
- 建议在
go mod tidy后立刻检查go.mod是否新增了不该出现的包，尤其是// indirect标记的依赖——它们可能是某一级依赖的子依赖，但当前项目并未直接 import - CI 流水线中务必包含
go mod tidy -v并比对输出，防止go.mod被手动修改绕过检查 - 不要在
go.mod里手动增删require行；所有变更都该由go get或go mod tidy自动生成
go.sum 不是“校验文件”而是“信任锚点”，不能忽略或删掉
go.sum 记录每个依赖模块的 checksum，Go 命令每次下载时都会核对。一旦发现不一致，就拒绝构建，并报错：verifying github.com/some/pkg@v1.2.3: checksum mismatch。这不是警告，是硬性失败。
立即学习“go语言免费学习笔记（深入）”；
为什么容易被忽略：
• 它不参与编译，也不影响本地开发流程
• 新人常以为它是“缓存”或“日志”，随手 git clean -fdx 连它一起删了
• 某些 IDE 插件会标灰它，让人误以为可忽略
-
go.sum必须和go.mod一起提交到 Git —— 它们是一对绑定的完整性凭证 - 如果遇到 checksum mismatch，优先检查是否有人手动修改过
go.mod、是否用了非官方代理（如没配GONOPROXY导致私有包走错了源）、或者依赖本身被篡改（极少见，但需警惕） - 不要用
go mod download -x查看下载过程来“绕过”校验；真要跳过（仅限调试），得用GOINSECURE环境变量，但这会彻底关闭校验，生产环境禁用
replace 和 exclude 不是“快捷方式”，而是明确的工程决策信号
当你要用本地修改的 fork 版本，或想屏蔽某个有安全问题的间接依赖时，replace 和 exclude 才是合法手段。但它们会改变模块解析行为，影响所有协作者。
典型误用：
• 为“加快下载”把公共包 replace 到公司内网镜像地址（应该用 GOPROXY，不是 replace）
• 把还没发布的功能分支用 replace 指向本地路径，却没在 README 写明，导致别人 clone 后无法构建
-
replace后的路径如果是本地目录（如./my-forked-lib），该目录下也必须有合法的go.mod，且模块路径要和原依赖一致 -
exclude只能排除间接依赖，不能排除直接require的包；排除后若某一级依赖仍硬依赖它，构建会失败 - 所有
replace和exclude都应在 PR 描述中说明原因，并附上对应 issue 或安全公告链接
go.sum 被删、replace 没同步、或者 internal/ 里偷偷 import 了不该用的包——这些细节不显眼，但会让整个团队卡在构建环节。 
