真正的传统 vendor 项目指无 go.mod 文件、GO111MODULE=off、依赖手动管理且 vendor/ 路径与 import 路径严格对应；常见误判是存在 go.mod 却保留 vendor/，实为混合模式。
确认当前项目是否真属于“传统 vendor”模式
真正的传统 vendor 项目指：没有 go.mod 文件、GO111MODULE=off 或 auto、依赖全靠手动复制或 govendor 管理，且 vendor/ 目录下包路径与 import 路径严格对应（如 import "github.com/pkg/errors" → vendor/github.com/pkg/errors/）。
常见误判点：
- 项目有
go.mod但同时保留vendor/—— 这已是模块+vendor 混合模式，不是“传统” -
vendor/vendor.json存在但go.mod为空或缺失 —— 才算传统 vendor - 运行
go env GO111MODULE输出off，且go list -m报错no modules found，才是典型信号
初始化模块并迁移依赖声明
不能直接跑 go mod init 就完事。传统 vendor 里没版本约束，而 go mod 需要明确的版本锚点，否则 go mod tidy 会拉最新版，极易引入不兼容变更。
安全做法是优先从 vendor/ 中提取已知可用版本：
立即学习“go语言免费学习笔记（深入）”；
- 用
go list -f '{{.ImportPath}} {{.Dir}}' all 2>/dev/null | grep -v '/vendor/'获取主代码实际 import 的包路径 - 对每个路径，查
vendor/下对应目录的git log -n1 --oneline或git describe --tags（如果 vendor 是 git submodule 或带 .git） - 手动写入
go.mod：require github.com/pkg/errors v0.9.1（别信go get自动猜的版本） - 若 vendor 无 git 信息，就用
go mod graph | grep 包名辅助定位间接依赖版本，或翻历史构建日志
清理 vendor 并验证模块行为
生成 go.mod 后，go mod tidy 会重新拉取依赖并写入 go.sum，此时 vendor/ 已失效，必须删掉，否则干扰判断。
关键验证步骤：
- 删掉
vendor/目录后，go build仍能成功 —— 说明模块配置完整 - 运行
go list -m all | wc -l和go list -f '{{if not .Indirect}}{{.Path}}{{end}}' all | wc -l，确认直接依赖数量与原 vendor 中顶层包数大致匹配 - 检查
go.sum是否包含所有依赖的校验和；若缺某些// indirect包的 checksum，说明它们未被主代码实际引用，可忽略 - CI 流水线中移除
-mod=vendor参数，并确保GO111MODULE=on—— 否则旧逻辑还在偷偷走 vendor
处理私有仓库和 replace 场景
传统 vendor 常通过脚本把私有库 cp 进 vendor/，模块模式下必须显式声明，否则 go mod tidy 会卡住或报 unknown revision。
正确做法：
- 提前配置
GOPRIVATE=git.example.com/internal/*（通配符必须），避免 go 命令试图走 proxy - 若私有库尚未打 tag，用
replace github.com/your-org/private => ./local-private写进go.mod，再go mod tidy -
replace不影响go mod vendor行为 —— 它只复制go.mod中最终解析出的路径，所以本地路径不会进 vendor，这是预期行为 - 切勿在迁移初期混用
replace和vendor/，会导致go build加载路径混乱
重构最难的部分不在命令执行，而在版本对齐：vendor 目录本身不记录语义化版本，你得靠 commit hash、release note 或团队记忆去还原当初锁定的是哪个 commit。漏掉一个 // indirect 依赖的版本，就可能让 go mod tidy 拉到破坏性更新。
