模块路径变更后需同步更新 import 路径并重生成 go.sum：先删除 go.sum（保留 go.mod），再执行 go mod tidy；同时用 grep 和 sed 批量替换所有旧 import 路径，避免编译失败或循环依赖。
模块路径变更后 go mod tidy 报错 “missing go.sum entry”
模块路径改了，但旧的校验和还留在 go.sum 里，go mod tidy 会拒绝加载新路径的依赖，直接报这个错。本质是校验和不匹配，不是网络或权限问题。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 先删掉
go.sum（别删go.mod），再跑go mod tidy—— 它会重新拉取依赖并生成新校验和 - 如果项目有 CI/CD，确保构建前清空
go.sum或用go mod tidy -e暴露所有错误再处理 - 多人协作时，
go.sum必须提交，否则队友本地会因校验和缺失而构建失败
重命名模块后，import 路径没同步更新导致编译失败
Go 不像 Java 那样靠 IDE 自动修复 import，模块路径改了，所有 import 语句里的旧路径都得手动或脚本批量替换，否则 go build 直接报 cannot find package。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
grep -r "old/module/path" . --include="*.go"扫描全部引用点 - 用
sed -i '' 's/old\/module\/path/new\/module\/path/g' $(grep -rl "old/module/path" . --include="*.go")（macOS）或对应 Linux 版本批量替换 - 别漏掉测试文件、example 文件、甚至
go:embed引用的路径字符串
重构中跨模块调用出现循环依赖：A 依赖 B，B 又间接依赖 A
模块拆分初期最容易踩的坑。表面上看 A 和 B 是平级模块，但 B 的某个子包 import 了 A 的内部工具函数，Go 的模块系统会把整个 A 当作依赖引入，触发循环。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
go list -f '{{.Deps}}' ./a查看 A 的直接依赖，确认是否意外引入了 B - 把公共逻辑抽成独立的
internal模块或pkg模块，让 A 和 B 都只依赖它，而不是互相依赖 - 避免在
go.mod中用replace临时绕过循环——这会让依赖图失真，上线前必须删掉
升级主模块版本号（如 v1 → v2）后，老代码仍能编译通过但行为异常
v2+ 模块要求路径末尾带 /v2，但 Go 不强制校验语义版本行为。如果只是改了 go.mod 里的 module 行，没改函数签名或返回值，编译能过，但 runtime 可能 panic 或静默出错。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 版本号升级必须同步做两件事：改
module声明路径 + 改所有 import 路径（含测试） - 用
go list -m all | grep your-module确认当前项目实际加载的是哪个版本 - 关键接口变更务必加
go:build约束或文档注释，提醒调用方注意破坏性变更
replace 写错，或者一个 import 漏改，都可能让线上服务在几天后才暴露问题。 
