老项目启用Go Modules需谨慎清理vendor等残留机制，确认GO111MODULE非off，go mod init后须go mod tidy再go mod vendor，并校验fork变更；CI中应禁用GOPATH依赖、使用go install安装工具、加-mod=readonly防止意外修改。
Go项目还在用 GOPATH？先确认是否真能直接启用 Modules
不是所有老项目都能一键 go mod init 就完事。如果项目里存在 vendor/ 目录、Gopkg.lock（dep）、glide.yaml 或手动维护的 src/ 路径，直接初始化会漏依赖或拉错版本。必须先清理或评估这些残留机制。
检查当前环境：
go version go env GOPATH GO111MODULE确保
GO111MODULE 不是 off（Go 1.16+ 默认为 on，但旧项目可能被显式设为 off）。
- 若
GO111MODULE=off，临时启用：运行前加GO111MODULE=on go mod init example.com/myproj - 若项目路径不在
$GOPATH/src下，且没设GO111MODULE=on，go mod命令会被静默忽略 -
go mod init的参数必须是模块路径（如github.com/user/repo），不能是本地文件路径或空字符串
go mod init 后 vendor 目录没生成？别急着手动复制
go mod init 只生成 go.mod，不触碰 vendor/。要还原 vendor，得显式执行 go mod vendor —— 但这个命令有陷阱：
- 它只 vendoring
go list -deps ./...能发现的包，如果项目里有未被 import 的测试依赖（比如_test.go里用的包），它们不会进vendor/ - 如果原
vendor/里有非标准路径的 fork（如github.com/user/pkg@fork-branch），go mod vendor默认按go.mod里记录的 commit 或 tag 拉取，可能丢失定制修改 - Go 1.18+ 默认禁用
-mod=vendor，想强制走 vendor 编译，得加go build -mod=vendor
推荐做法：先 go mod tidy 确保 go.mod 和 go.sum 准确，再 go mod vendor；之后用 diff -r vendor/ old_vendor/ 对比关键包，人工校验 fork 是否被覆盖。
升级后 CI 构建失败？重点查这三个地方
CI 脚本里常见硬编码路径或假设，Modules 启用后容易崩：
-
export GOPATH=$HOME/go+go get仍会写入$GOPATH，但主模块已不依赖它——应删掉所有go get安装工具类命令（如golint），改用go install golang.org/x/lint/golint@latest（Go 1.17+） - 构建命令含
CGO_ENABLED=0 go build但没加-mod=readonly，可能导致意外写入go.mod（尤其当代码里 import 了新包但没go mod tidy） - Docker 多阶段构建中，
FROM golang:1.19镜像默认开启 Modules，但如果 COPY 进来的源码没有go.mod，go build会退化为 GOPATH 模式并报错no Go files in ...
CI 中最稳的构建命令是：
go mod tidy -v go build -mod=readonly -o myapp .
replace 和 exclude 不是万能补丁，小心破坏语义化版本约束
遇到私有仓库、未发布分支或冲突依赖时，容易滥用 replace：
-
replace github.com/old/pkg => ./local-pkg：本地路径替换在 CI 中失效，必须同步提交local-pkg/或改用replace github.com/old/pkg => github.com/fork/pkg v1.2.3 -
exclude module v1.5.0只阻止该版本被选中，但若其他依赖明确 requirev1.5.0，go build仍会失败，此时该用replace强制降级 - 多个
replace指向同一模块不同 commit，Go 会取最后一个，但go mod graph不显示这种覆盖，排查困难
真正需要 patch 的场景，优先考虑 go mod edit -replace + 提交 go.mod，而不是靠本地 go.work 或环境变量临时绕过。
Modules 的核心其实是「可重现」，不是「能编过」。任何绕过 go.sum 校验、跳过 go mod verify、或依赖未声明的 vendor/ 内容的操作，都会在换机器、换 Go 版本时暴露问题。
