必须立即执行go mod tidy：go mod init仅生成空go.mod，不声明依赖、不校验import，若代码含第三方import（如"github.com/gorilla/mux"），后续go build会报“cannot find package”；tidy则补全require、清理未用依赖、生成go.sum并拉取最小版本。
go mod init 之后必须立刻 go mod tidy
初始化模块后不立即整理依赖，会导致后续构建失败或行为不可预测。比如 go mod init myapp 只生成空的 go.mod，但没声明任何依赖；而你代码里 import 了 github.com/gorilla/mux，go build 就会报错“cannot find package”。go mod tidy 不只是补全依赖，它还会：删除未使用的模块、拉取最小版本、校验 go.sum 一致性。
常见错误现象：go run main.go 报错 no required module provides package，本质就是依赖没被 go.mod 记录。
- 执行前确保当前目录是项目根（即含
main.go和go.mod的目录） - 如果项目已有 vendor 目录，
go mod tidy默认忽略它；加-mod=mod强制以模块模式操作 - CI 环境中建议固定 Go 版本（如
1.22.6），避免因本地 Go 升级导致go.sum哈希变更
替换私有仓库或本地路径用 replace 而不是修改 import path
当你在开发中要临时调试一个还没发布的内部库，或者公司私有 Git 仓库无法通过公共代理访问时，硬改代码里的 import "github.com/org/lib" 是危险且不可维护的。正确做法是在 go.mod 里用 replace 指令重定向。
示例：你想让 github.com/org/lib 指向本地修改过的副本：
replace github.com/org/lib => ../lib
或指向私有 Git 地址：
replace github.com/org/lib => git@company.com:org/lib.git v1.2.0
注意：replace 只在当前模块生效，不会影响下游依赖；它也不改变源码中的 import 路径，所以团队协作时无需同步改代码。
-
replace必须写在go.mod的require块之后，否则go mod tidy会把它删掉 - 生产构建前应移除或注释掉
replace（尤其指向本地路径的），否则 CI 会找不到目标目录 - 若用 SSH 地址，确保 CI 机器已配置对应密钥；HTTP 地址则需配好
GOPROXY或git config --global url."https://token@company.com/".insteadOf "https://company.com/"
go.sum 不要手动编辑，但得理解它为什么变
go.sum 是 Go 模块的完整性校验文件，记录每个依赖模块版本的哈希值。它不是锁文件，而是“内容指纹”——哪怕同一版本的模块，只要源码有微小改动（比如注释增删），哈希就不同。所以你看到 go.sum 变更，大概率不是出错，而是上游真的改了。
容易踩的坑：
- 提交时漏掉
go.sum→ 其他人go build失败，报 “checksum mismatch” - 误删
go.sum后直接go mod tidy→ 新生成的文件可能包含不同 commit 的哈希，导致构建结果不一致 - 多人协作时，有人用 Go 1.21，有人用 1.22 →
go.sum格式微调（如新增空行），Git 显示大量 diff，但实际不影响功能
判断是否真有问题：运行 go mod verify。如果输出 “all modules verified”，说明没问题；否则检查网络、代理或是否混用了 replace 和远程版本。
多模块协同开发用 go.work，别硬套 GOPATH 思路
当项目拆成多个子模块（如 api/、service/、shared/），且它们之间有本地依赖时，go work 是唯一干净的解法。不要试图用符号链接、GOPATH 多路径或反复 go mod edit -replace —— 那些方式在 IDE 里失效、在 CI 里断裂、在团队里难同步。
关键动作只有两步：
- 在工作区根目录（比如
~/project）执行go work init ./api ./service ./shared，生成go.work - 每个子目录保持独立
go.mod，go.work会让go命令自动把本地路径当作最高优先级源
注意：go.work 文件本身不参与版本发布，只用于本地开发；上线部署时仍走各子模块自己的 go.mod 和远程 tag。如果你在 api 里 import ./shared，IDE 能跳转、go test 能跑通、go build 不报错——这才是预期行为。
真正容易被忽略的是：一旦启用了 go.work，所有 go 命令（包括 go mod tidy）都会受它影响。如果某个子模块单独构建失败，先 cd 出工作区再试，排除工作区干扰。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
