Go 依赖管理从 GOPATH 到 module 的演进
写 Go 久了会发现，依赖管理这块它折腾过好几版：最早的 GOPATH 把所有代码塞一个目录，后来 vendor 把依赖拷进项目救急，再到现在的 go module 彻底解绑目录。这篇按时间线把三个阶段讲清楚，每一代解决了什么、又留下什么坑，顺带说说为什么今天直接用 module 就对了。
现在上手 Go，go mod init 一敲，依赖的事基本就不用操心了。
但你要是接手过几年前的老项目，大概率会撞上一堆奇怪的东西：GOPATH 环境变量、src 目录、vendor 文件夹……
这些都是 Go 依赖管理一路折腾下来的历史遗留。
我自己从 GOPATH 时代一路用过来，踩过的坑能写一箩筐。
这篇就按时间线，把 Go 依赖管理的三个阶段捋一遍：它为什么要这么设计、每一代解决了啥、又留下了啥新麻烦。
搞懂这条演进线，你再看那些老项目就不会一脸懵了。
GOPATH 一切都在一个篮子里
Go 最早的依赖管理，核心就一个环境变量：GOPATH。
它的思路非常简单粗暴：所有 Go 代码，都得放在 GOPATH 指定的目录下。
# GOPATH 指向的目录，内部是固定的三件套结构
$GOPATH/
├── src/ # 所有源码都放这里，包括你自己的和第三方的
├── pkg/ # 编译生成的归档文件（.a）
└── bin/ # go install 装出来的可执行文件
重点在 src。
你自己的项目、你 go get 下来的所有第三方库，统统平铺在 src 下面，按包的导入路径组织成目录。
比如你 go get github.com/gin-gonic/gin，它就被放到 $GOPATH/src/github.com/gin-gonic/gin。
你 import 的时候写的路径，其实就是它在 src 下的目录路径。
这套设计的好处是规则统一：导入路径 = 目录路径，一一对应，编译器闭着眼都能找到包。
但问题也随之而来，而且是致命的那种。
第一个坑 项目必须放在固定目录
你的代码不能随便放。
想在桌面建个项目练手？不行，必须塞进 $GOPATH/src/xxx 里，否则 go build 直接找不到包。
这个限制在当年劝退了不少新手。
明明是我自己的代码，凭什么不能想放哪放哪？
第二个坑 根本没有版本概念
这才是真正要命的。
GOPATH 模式下，一个第三方库在 src 里只能存在一个版本。
$GOPATH/src/github.com/some/lib <- 这里只有一份，就是最新拉下来的那份
你 go get 拉的永远是最新代码，没有地方记录“我这个项目依赖的是哪个版本”。
想象一下这个场景：
- 项目 A 依赖 lib 的 v1 版本
- 项目 B 依赖同一个 lib 的 v2 版本
两个项目共用一个 GOPATH，这个 lib 在 src 里只能放一份。
你给 A 用 v1，B 就跑不了；给 B 用 v2，A 就崩了。
无解。
这就是著名的“钻石依赖”问题，GOPATH 对此束手无策。
团队协作更惨：你机器上拉的 lib 和同事拉的可能不是同一天的代码，编译结果都未必一致，出了 bug 根本没法复现。
vendor 把依赖搬进项目
为了救 GOPATH 的版本之痛，Go 1.5 引入了 vendor 机制。
思路也很直白：既然共用一份依赖会打架，那就让每个项目自带一份。
做法是在项目根目录下建一个 vendor 文件夹，把项目用到的所有第三方依赖原样拷贝进去。
my-project/
├── main.go
└── vendor/ # 本项目专属的依赖仓库
└── github.com/
└── gin-gonic/
└── gin/ # gin 的源码直接拷进来
编译时，Go 有个优先级规则：
先在当前项目的
vendor目录里找依赖，找到了就用它，找不到才去 GOPATH 里找。
这一下就解决了版本冲突。
项目 A 的 vendor 里放 lib v1，项目 B 的 vendor 里放 lib v2，各用各的，井水不犯河水。
而且依赖跟着项目走，你把整个项目（含 vendor）打包给别人，对方不用 go get，直接就能编译，依赖版本还完全一致。
这在当年是个巨大的进步。
但 vendor 自己也不完美。
它只解决了“依赖放哪、怎么隔离”的问题，却没解决**“版本怎么记录和管理”**。
- vendor 里的代码是哪个版本？看不出来，就是一堆源码文件
- 想升级某个依赖？得手动把新代码拷进去，容易拷错拷漏
- vendor 目录往往很大，一堆第三方源码塞进 git 仓库，代码量虚高
所以当时社区冒出来一堆第三方工具（dep、glide、govendor 这些），专门帮你管 vendor 里到底装了哪些版本。
百花齐放，但也意味着没有标准，换个项目可能就换一套工具，心智负担不小。
Go 官方显然也看到了这个乱象。
go module 终于解绑目录
Go 1.11 推出了 module（go mod），1.13 之后成为默认，彻底终结了前面所有的拧巴。
它一次性干掉了两个历史包袱：
- 项目不用再放 GOPATH 里了，想放哪放哪
- 依赖版本有了明确的记录和锁定
核心是两个文件：go.mod 和 go.sum。
go.mod 声明依赖和版本
go mod init 之后，项目根目录会生成一个 go.mod：
module github.com/mebugs/my-project // 本项目的模块路径
go 1.21 // 要求的 Go 版本
require (
github.com/gin-gonic/gin v1.9.1 // 依赖哪个库、哪个版本，写得明明白白
github.com/go-redis/redis/v8 v8.11.5
)
看到没，依赖和版本号白纸黑字写在这里。
这正是 GOPATH 和 vendor 都缺的东西。
谁拉这个项目，go build 一跑，Go 自动按 go.mod 里写的版本去下载对应的依赖，大家编译出来的东西完全一致。
go.sum 校验依赖没被篡改
go.sum 存的是每个依赖的哈希校验值。
github.com/gin-gonic/gin v1.9.1 h1:xxxx... // 这个版本代码的指纹
github.com/gin-gonic/gin v1.9.1/go.mod h1:yyyy...
每次下载依赖，Go 会拿下载到的代码算哈希，跟 go.sum 里记的对一遍。
对不上说明代码被改过（可能是网络劫持、也可能是源头被人动了手脚），直接报错拒绝编译。
这是一道安全防线，保证你今天拉的依赖和当初锁定的是同一份东西。
依赖存哪了
module 模式下，下载的依赖不再堆在 GOPATH/src，而是放进一个带版本号的全局缓存：
$GOPATH/pkg/mod/ # module 缓存目录
└── github.com/
└── gin-gonic/
├── [email protected]/ # 不同版本和平共处！
└── [email protected]/
注意目录名带了 @版本号。
这意味着同一个库的多个版本可以同时缓存在本地，不同项目各取所需，GOPATH 时代“只能存一份”的死结彻底解开了。
常用命令也简单：
go mod init example.com/myapp # 初始化，生成 go.mod
go get github.com/xxx/[email protected] # 拉指定版本的依赖
go mod tidy # 自动整理：补上缺的、删掉没用的依赖
go mod download # 把 go.mod 里的依赖都下载到本地缓存
我个人最爱 go mod tidy。
写完代码敲一下，它自动把你 import 了但没声明的依赖补进 go.mod，把你声明了却没用的清出去，省心得很。
那 vendor 现在还有用吗
有意思的是，module 时代 vendor 并没有完全退场。
你可以执行 go mod vendor，它会按 go.mod 把所有依赖拷贝一份到 vendor 目录。
然后用 go build -mod=vendor 优先走本地 vendor 编译。
这跟当年的 vendor 看着一样，但本质不同了：现在的 vendor 是由 go.mod 精确生成的，版本可控、内容可复现，不再是手工拷贝的黑盒。
什么场景还会用它？
- 内网环境，编译机连不了外网，没法下载依赖，就把 vendor 一起提交进去
- 对构建的绝对可复现有要求，不想依赖外部网络和缓存
所以今天的 vendor 更像是一个“离线快照”选项，而不是依赖管理的主力方案。
小结
把这条演进线串起来看，其实就是一个不断解决问题的过程：
- GOPATH：规则简单，但强制统一目录、且完全没有版本概念，多项目依赖直接打架
- vendor（早期）：把依赖拷进项目实现隔离，解决了冲突，但版本管理全靠第三方工具，没有标准
- go module：go.mod 记版本、go.sum 保校验、带版本号的全局缓存，一次性解决目录绑定和版本管理两大难题
对今天的我们来说，结论很干脆：新项目直接上 go module，别碰 GOPATH 那一套。
只有在接手老项目、或者有离线构建这种特殊需求时，才需要回头了解 GOPATH 和 vendor 是怎么回事。
搞懂了这条线，你再看到老代码里的 GOPATH 和 vendor，心里就有数了，知道它们当年是为了解决什么而存在的。
那就 go mod init 一下，开个新项目练练吧。