Go Module是Go语言官方推出的依赖管理方案，相比之前的GOPATH和vendor模式，它能更精准地管理依赖版本，支持项目脱离GOPATH目录运行。很多团队在迁移完成后，因为忽略了一些细节问题，反而导致项目出现各类异常，下面我们就来梳理迁移后需要重点关注的要点。
依赖版本相关注意事项
确认依赖版本锁定
迁移完成后，首先要检查go.sum文件是否生成完整，这个文件会记录所有依赖的哈希值，保证依赖内容的一致性。如果go.sum缺失或者内容不全，可能会导致不同环境下拉取的依赖内容不一致。
同时要注意go.mod中的版本声明，尽量使用明确的主版本号，避免使用latest这类模糊版本标识，防止后续依赖自动升级带来不兼容问题。如果需要固定某个依赖的版本，可以手动修改go.mod后执行go mod tidy更新依赖。
下面是一个简单的go.mod示例：
module ippipp.com/myproject
go 1.19
require (
github.com/gin-gonic/gin v1.9.1
github.com/go-sql-driver/mysql v1.7.1
)
require (
github.com/bytedance/sonic v1.9.1 // indirect
github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 // indirect
)
处理间接依赖问题
迁移后可能会出现很多标记为// indirect的间接依赖，这些是项目直接依赖所引用的第三方库。不要随意删除这些间接依赖，除非你确认项目确实不再需要它们。如果间接依赖出现版本冲突，可以通过go mod why命令查看该依赖被引入的原因，再针对性处理。
导入路径调整注意事项
如果项目之前的导入路径和module声明的路径不一致，迁移后需要统一调整所有代码中的导入路径。比如go.mod中声明的模块路径是ippipp.com/myproject，那么项目内部包的导入路径也需要以这个为前缀，否则会出现导入失败的问题。
如果项目需要同时兼容旧的导入路径，可以在go.mod中使用replace指令做路径映射，不过这只建议作为过渡方案，后续还是要逐步统一导入路径。
替换路径的配置示例如下：
module ippipp.com/myproject go 1.19 replace old.import/path => ippipp.com/myproject
构建与运行相关注意事项
关闭旧模式兼容配置
迁移前如果设置了GO111MODULE环境变量为auto或者off，迁移后建议将其设置为on，或者直接在项目中去掉这个环境变量配置，避免Go编译器回退到旧的依赖管理模式，导致module配置不生效。
清理旧的依赖文件
迁移完成后，建议删除项目中的vendor目录（如果之前使用vendor模式的话），以及GOPATH中相关的项目缓存，避免旧的依赖文件干扰新模式的构建。之后可以通过go mod download命令拉取所有依赖到本地缓存，验证依赖拉取是否正常。
兼容性与协作注意事项
如果团队中还有成员没有升级Go版本，需要确认所有人的Go版本都支持Go Module，建议统一使用高于1.13的Go版本，避免低版本Go不支持部分module特性。同时要把go.mod和go.sum都提交到版本控制系统中，不要将这两个文件加入.gitignore，保证所有成员的依赖版本一致。
如果项目有发布版本的需求，需要遵循语义化版本规范，主版本升级（v2及以上）的时候，需要在模块路径后加上主版本号，比如module ippipp.com/myproject/v2，否则会导致依赖引用异常。
常见问题排查
如果遇到依赖拉取失败的问题，可以先检查网络是否能正常访问依赖所在的代码托管平台，必要时可以配置GOPROXY环境变量使用国内代理。如果出现版本冲突，可以通过go mod graph命令查看依赖关系图，定位冲突的依赖版本，再手动调整go.mod中的版本声明。
如果构建的时候提示找不到包，首先检查导入路径是否和go.mod中的模块路径匹配，然后执行go mod tidy自动清理无用依赖并补充缺失的依赖，再重新构建验证。