go modules 迁移核心是确保构建一致性：先确认 go111module 状态与 go.mod 存在性，再用 go mod init 初始化并修正 import 路径，注意 vendor/ 与 go.sum 处理、私有仓库配置及 ci 环境 go 版本统一。
Go Modules 是 Go 1.11+ 的标准依赖管理方式，所有 GOPATH 项目都应迁移——不是“要不要”，而是“怎么迁得稳、不破现有构建和 CI”。
确认当前项目是否已启用 Go Modules
别猜，直接看 go env GO111MODULE 和项目根目录有没有 go.mod。如果输出 off 且没有 go.mod，那就是纯 GOPATH 模式。注意：即使 GO111MODULE=on，若项目不在 $GOPATH/src 下且无 go.mod，go build 仍会 fallback 到 GOPATH 模式，行为不一致是第一个坑。
- 运行
go mod init example.com/myproject初始化模块（模块路径建议用真实域名或可标识的前缀，别用main） - 初始化后立即执行
go build或go test，观察是否报错找不到包——这说明某些本地import路径（如"mylib"）还指向 GOPATH 相对路径，需手动修正为完整模块路径 - 如果项目有
vendor/目录，先删掉再 init；否则go mod可能误读 vendor 内容，导致依赖版本混乱
处理 import 路径不兼容问题
GOPATH 时代习惯写 "utils" 或 "server/handler" 这类短路径，但 Go Modules 要求 import 路径必须与 go.mod 中声明的模块路径匹配。硬改所有 import 既费时又易漏，关键是识别哪些必须动、哪些可以不动。
- 本地子包（如
./config、./internal/db）不用改，点号路径始终有效 - 原在
$GOPATH/src/github.com/user/repo下的跨项目引用，现在必须写成"github.com/user/repo/config"，否则编译失败 - 如果旧项目用了
replace指向本地路径（如replace example.com/lib => ../lib），确保../lib目录下也有合法go.mod，否则go build会静默忽略 replace 并报错 - 用
grep -r 'import "' . --include="*.go" | grep -v '^\.' | grep -v '"/'快速扫出疑似短路径 import，人工核对
go.sum 和 vendor 的取舍策略
go.sum 记录依赖哈希，保障可重现构建；vendor/ 是 GOPATH 时代的“离线副本”。迁移到 Modules 后，二者不是二选一，而是根据场景决定是否保留 vendor。
立即学习“go语言免费学习笔记（深入）”；
- CI 环境强烈建议保留
vendor/：执行go mod vendor生成，然后 CI 中加-mod=vendor参数，避免网络抖动或上游模块被删导致构建失败 -
go.sum必须提交到 Git，它是依赖完整性的唯一凭证；删掉它等于放弃校验，下次go get可能拉到被篡改的包 - 如果项目长期不更新依赖，
go mod tidy可能误删间接依赖（_test.go里用到但未显式 import 的包），建议先跑一遍go test ./...再 tidy - 私有仓库（如 GitLab 自建）需配置
go env -w GOPRIVATE=git.example.com/internal，否则go get会尝试走 proxy 并失败
CI/CD 和多环境构建常见断裂点
本地能过 ≠ CI 能过。很多团队卡在 Jenkins/GitLab CI 上，根本原因是环境变量和 Go 版本不一致。
- CI 脚本里别写
export GOPATH=...，Modules 模式下 GOPATH 仅影响go install默认位置，干扰反而大 - 确保 CI 使用 Go ≥ 1.16（推荐 1.19+），低于 1.16 的
GO111MODULE默认是auto，行为更难预测 - Docker 构建时，如果 base image 是
golang:alpine，注意 Alpine 的ca-certificates包可能缺失，导致go get报x509: certificate signed by unknown authority，加apk add ca-certificates - 本地开发用 VS Code + Go 插件？检查设置里
"go.useLanguageServer": true和"go.toolsEnvVars"是否覆盖了GO111MODULE=on，否则编辑器提示和命令行行为不一致
最麻烦的不是命令怎么敲，而是那些没报错但悄悄走回 GOPATH 路径的 case——比如 go run main.go 成功，但 go build -o app . 失败，往往是因为某个测试文件 import 了未声明的本地包，只在 test 模式下触发。上线前务必用 go list -deps -f '{{if not .Standard}}{{.ImportPath}}{{end}}' ./... 扫一遍真实依赖树。
