前面几篇基本上都是单文件写代码但实际项目不可能只有一个 main.go。当你开始拆分包、引入第三方库的时候就绕不开 Go Modules。这篇把我从 GOPATH 时代过渡到 Modules 过程中踩过的坑、弄明白的原理整理一下。Go 1.11 引入 Modules1.16 起默认开启现在基本没人用 GOPATH 了。为什么需要 Go Modules在 Go Modules 之前所有代码必须放在$GOPATH/src目录下而且依赖管理基本靠手动go get没有版本概念。同一个项目里不同依赖如果依赖同一个库的不同版本会直接冲突。Go Modules 解决了两个核心问题项目可以放在任意目录不再局限于 GOPATH。依赖有了版本记录可复现构建。还记得我刚学 Go 的时候看到网上很多老教程还在讲 GOPATH结果照着做总是报错后来才知道时代变了。初始化模块在项目根目录执行go mod init github.com/username/project会生成一个go.mod文件内容大致如下module github.com/username/project go 1.22 require ( github.com/gin-gonic/gin v1.9.1 golang.org/x/text v0.14.0 // indirect )module声明模块路径一般是仓库地址。go声明编译器版本。require列出直接依赖和间接依赖标记// indirect。模块路径很重要它决定 import 前缀。比如模块路径是github.com/username/project那么项目内的包就通过github.com/username/project/包名导入。go.mod 文件详解go.mod 里常见指令module模块路径。goGo 版本。require声明依赖模块及版本。replace替换依赖路径或版本常用于本地调试或替换有问题的版本。exclude排除某个版本防止被拉取。retract标记某个版本有严重问题建议不要使用Go 1.16。平时最常用的就是require和replace。依赖下载go get 与 go mod tidygo get添加或更新依赖用go getgo get github.com/gin-gonic/ginv1.9.1可以指定版本也可以不带版本号默认拉取最新稳定版实际上是 latest。如果只想拉取最新 patch 版本可以用v1.9Go 会自动选择该主版本下最新的补丁版本。go mod tidy这个命令会扫描代码里的 import自动添加缺失的依赖移除未使用的依赖。建议每次提交代码前都跑一遍保持 go.mod 干净。我刚用的时候每次go get完总是忘记tidy结果 go.mod 里一堆没用的依赖后来养成了习惯改完 import 就go mod tidy。版本规则与伪版本Go Modules 使用语义化版本格式为vX.Y.ZX主版本不兼容的 API 变更。Y次版本向后兼容的新功能。Z补丁版本向后兼容的 bug 修复。如果依赖仓库没有打 tag或者拉取的是某个 commit就会生成一个伪版本形如v0.0.0-20240101120000-abcdef123456前面是v0.0.0后面是时间戳和 commit 哈希。伪版本在开发中很常见不用太困惑正常使用即可。有一点需要注意主版本升级到 v2 及以上时模块路径必须加上版本后缀比如github.com/foo/bar/v2否则 Go 会认为这是不同的模块。这个规则坑了不少人包括我。replace 指令本地调试和替换依赖如果你要调试一个第三方库或者临时替换成自己 fork 的版本可以用replacereplace github.com/original/lib ../local/lib replace github.com/original/lib github.com/myfork/lib v1.2.3这样代码里 import 不变实际加载的是替换后的路径。调试结束后记得删掉或改成正式版本。我平时调试一些开源库时先把库 clone 到本地然后在 go.mod 里replace指向本地路径改完代码直接测试非常方便。工作区模式Go 1.18当多个模块需要同时开发时以前需要不停改replace非常麻烦。Go 1.18 引入了工作区模式可以在一个工作区里同时包含多个模块。在父目录执行go work init ./module1 ./module2会生成go.work文件go 1.22 use ( ./module1 ./module2 )这样模块之间就可以直接相互 import不需要 replace。对于微服务项目或者多模块仓库非常实用。需要注意的是go.work文件一般不要提交到代码仓库它主要是本地开发用的。但如果是单仓库多模块提交也无妨看团队约定。vendor 目录离线构建默认情况下依赖下载到$GOPATH/pkg/mod目录构建时从那里读取。如果公司有网络安全限制或者需要离线构建可以把依赖复制到项目的vendor目录go mod vendor会生成vendor/目录包含所有依赖的源码。之后构建时如果存在 vendor 目录Go 会优先使用它但需要在构建命令加-modvendor参数Go 1.14 后自动检测。vendor 目录体积很大一般不需要提交除非有特殊需求。常用命令速查go mod init初始化模块。go mod tidy整理依赖。go mod download下载依赖到本地缓存。go mod vendor生成 vendor 目录。go list -m all列出所有依赖模块。go list -m -u all列出可升级的依赖模块。go get -u ./...升级所有依赖到最新版本谨慎使用。我踩过的坑把 GOPATH 和 Modules 混用早期看老教程在 GOPATH 下创建项目然后执行go mod init结果路径不对import 全乱。后来统一在 GOPATH 外创建项目。主版本 v2 忘记加后缀升级某个库到 v2 版本时import 路径没改结果编译报错。正确做法是 import 路径加上/v2go.mod 里也写上/v2。go get 后没有 tidy导致 go.mod 里一堆多余依赖提交代码被同事说了一顿。现在每次改完 import 顺手 tidy。replace 忘删本地调试完忘了删 replace结果 CI 构建时找不到本地路径直接失败。教训是调试结束立刻删 replace。go.work 和 go.mod 冲突工作区模式下go.mod 的 replace 会被忽略如果依赖有问题需要在工作区文件里改。这个问题排查了好久。小结这篇把 Go Modules 的核心内容过了一遍go mod init初始化模块生成 go.mod。go get添加依赖go mod tidy整理依赖。版本遵循语义化版本主版本 v2 要加路径后缀。replace用于本地调试和替换依赖。工作区模式适合多模块开发。vendor 目录用于离线构建。包管理是 Go 工程化的基础搞清楚这些命令和规则日常开发就不会被依赖问题卡住了。下一篇准备聊聊 Go 的标准库常用包比如 fmt、strings、strconv、time、encoding/json 这些把最常用的函数和用法梳理一遍。标准库真的很丰富很多需求不需要第三方库就能解决。如果这篇文章对你有帮助欢迎点赞收藏评论区一起交流。