go项目迁移到module后核心是依赖管理逻辑变更，不再依赖$GOPATH和隐式vendor/；需确保Go≥1.16、清理旧配置与残留文件、正确初始化go.mod、处理私有仓库、保障CI环境一致性。
Go项目迁移到module后，最核心的问题是依赖管理逻辑彻底改变，不再依赖$GOPATH，也不再隐式读取vendor/目录（除非显式启用）。迁移本身不难，但若忽略细节，容易导致构建失败、版本混乱或CI环境行为不一致。
确保Go版本和GO111MODULE设置正确
Go 1.11起引入module，1.16起默认启用。建议使用Go 1.16+，避免手动开关GO111MODULE带来的不确定性。
- 检查
go version是否≥1.16；低于该版本需升级或显式设GO111MODULE=on - 删除
~/.bashrc或~/.zshrc中残留的export GO111MODULE=off等配置 - 确认当前项目根目录下没有
vendor/且无Gopkg.lock等旧包管理器残留文件（如dep）
正确初始化go.mod并清理历史痕迹
在项目根目录执行go mod init <module-name></module-name>，模块名应为可解析的导入路径（如github.com/yourname/project），而非本地路径或假名。
- 若项目曾用dep、glide等工具，先运行
go mod vendor前务必删掉原有vendor/目录，否则go build可能误用旧依赖 - 执行
go mod tidy自动下载依赖、写入go.mod和go.sum；它会移除未引用的require项，也补全间接依赖 - 检查
go.mod中是否有// indirect标记的行——它们表示未直接import但被依赖链拉入的模块，需确认是否合理
处理私有仓库与替代源（replace / exclude）
公司内网Git、github私有库或尚未发布正式tag的模块，常需额外配置才能拉取。
- 对私有域名（如
git.example.com），在~/.gitconfig中配置URL重写：[url "ssh://git@git.example.com/"] insteadOf = https://git.example.com/ - 临时替换某依赖为本地路径：在
go.mod中加replace github.com/some/lib => ./local-fork，调试完记得删掉 - 慎用
exclude——它会强制跳过某版本，可能导致兼容性问题；优先考虑用replace或升级上游
CI/CD与多环境一致性保障
Module模式下，go build结果依赖go.sum校验和与go.mod声明，但不同Go版本或网络环境可能触发隐式升级。
- CI脚本中固定Go版本（如
actions/setup-go@v4指定go-version: '1.21'），避免因SDK升级导致go mod tidy行为变化 - 每次提交前运行
go mod tidy && git diff --quiet go.mod go.sum || (echo "go.mod or go.sum changed" && exit 1)，防止遗漏更新 - 禁止在CI中执行
go get或go install修改go.mod——所有依赖变更必须经本地tidy验证并提交
基本上就这些。迁移不是一次性动作，而是建立新的协作契约：模块名即标识、go.sum即信任锚点、go mod tidy即标准操作。不复杂但容易忽略细节。