在 Go 1.11 之前，依赖管理是 Go 语言的一大痛点。GOPATH、vendor、dep 等方案各有缺陷。Go Modules 的出现彻底解决了这个问题，成为 Go 官方推荐的依赖管理方案。

1. 什么是 Go Modules？

Go Modules 是 Go 语言的依赖管理系统，它解决了以下问题：

  • 版本管理：明确指定依赖的版本
  • 可重现构建：确保不同环境构建结果一致
  • 依赖隔离：不同项目可以使用同一个包的不同版本

2. 初始化模块

2.1 创建新模块

1# 创建项目目录
2mkdir myproject
3cd myproject
4
5# 初始化模块
6# 模块路径通常是代码仓库地址
7go mod init github.com/username/myproject

这会生成 go.mod 文件：

1module github.com/username/myproject
2
3go 1.21

2.2 go.mod 文件结构

 1module github.com/username/myproject  // 模块路径
 2
 3go 1.21  // Go 版本
 4
 5require (
 6    github.com/gin-gonic/gin v1.9.1  // 直接依赖
 7    gorm.io/gorm v1.25.5
 8)
 9
10require (
11    github.com/gin-contrib/sse v0.1.0  // 间接依赖（由 gin 引入）
12    // ... 更多间接依赖
13) // indirect
14
15exclude (
16    github.com/some/package v1.2.3  // 排除某个版本
17)
18
19replace (
20    github.com/old/package => github.com/new/package v1.0.0  // 替换依赖
21)

3. 常用命令

3.1 添加依赖

 1# 方法一：直接在代码中 import，然后运行
 2go mod tidy
 3
 4# 方法二：手动添加
 5go get github.com/gin-gonic/gin@v1.9.1
 6
 7# 获取最新版本
 8go get github.com/gin-gonic/gin@latest
 9
10# 获取特定版本
11go get github.com/gin-gonic/gin@v1.8.0
12
13# 获取某个 commit
14go get github.com/gin-gonic/gin@abc1234

3.2 go mod tidy

最常用的命令，它会：

  • 添加缺失的依赖
  • 移除未使用的依赖
  • 更新 go.sum 文件
1go mod tidy

3.3 下载依赖

1# 下载所有依赖到本地缓存
2go mod download
3
4# 查看依赖存放位置
5go env GOMODCACHE
6# 通常是 ~/go/pkg/mod

3.4 查看依赖

1# 查看所有依赖（包括间接依赖）
2go list -m all
3
4# 查看依赖树
5go mod graph
6
7# 查看某个包为什么被引入
8go mod why github.com/some/package

3.5 升级依赖

1# 升级所有依赖到最新的小版本
2go get -u ./...
3
4# 升级到最新的主版本（可能有破坏性变更）
5go get -u=patch ./...
6
7# 升级特定包
8go get -u github.com/gin-gonic/gin

4. 版本管理

4.1 语义化版本 (Semantic Versioning)

Go Modules 遵循 SemVer 规范：v主版本.次版本.修订号

  • 主版本 (Major)：不兼容的 API 变更
  • 次版本 (Minor)：向后兼容的功能新增
  • 修订号 (Patch)：向后兼容的 Bug 修复
1v1.2.3
2│ │ └─ Patch: Bug 修复
3│ └─── Minor: 新功能
4└───── Major: 破坏性变更

4.2 主版本升级

当主版本 >= 2 时，模块路径需要包含版本号：

1// v1 版本
2import "github.com/some/package"
3
4// v2 版本（路径变化！）
5import "github.com/some/package/v2"

5. replace 指令

5.1 替换为本地路径

在开发时，可以将依赖替换为本地版本：

1replace github.com/some/package => ../local-package

5.2 替换为 fork 版本

1replace github.com/original/package => github.com/yourname/package v1.0.0

5.3 解决依赖冲突

1// 强制使用特定版本
2replace github.com/some/package => github.com/some/package v1.2.3

6. 私有仓库配置

6.1 配置 GOPRIVATE

1# 设置私有仓库前缀
2go env -w GOPRIVATE=github.com/yourcompany/*
3
4# 多个前缀用逗号分隔
5go env -w GOPRIVATE=github.com/company1/*,gitlab.com/company2/*

6.2 配置 Git 认证

1# 方法一：使用 SSH
2git config --global url."git@github.com:".insteadOf "https://github.com/"
3
4# 方法二：使用 Token
5git config --global url."https://username:token@github.com/".insteadOf "https://github.com/"

6.3 配置 GOPROXY

1# 使用国内代理（加速下载）
2go env -w GOPROXY=https://goproxy.cn,direct
3
4# 跳过代理直接访问私有仓库
5go env -w GOPRIVATE=github.com/yourcompany/*

7. go.sum 文件

go.sum 记录了每个依赖的哈希值，用于验证依赖完整性：

github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL7YrpYKXt5YId3A/Tnip5kqbEAP+KLuI3SUcPTeU=

注意：go.sum 应该提交到版本控制系统。

8. 最佳实践

  1. 始终使用 go mod tidy：在提交代码前运行，确保依赖干净
  2. 提交 go.sum：保证构建可重现
  3. 使用 replace 谨慎：只在开发时使用，生产环境应该移除
  4. 固定版本：避免使用 @latest，明确指定版本号
  5. 定期更新依赖：及时修复安全漏洞

9. 常见问题

9.1 依赖下载失败

1# 清理缓存
2go clean -modcache
3
4# 使用代理
5go env -w GOPROXY=https://goproxy.cn,direct

9.2 版本冲突

1# 查看冲突
2go mod graph | grep package-name
3
4# 使用 replace 强制指定版本

9.3 vendor 目录

1# 将依赖复制到 vendor 目录（可选）
2go mod vendor
3
4# 使用 vendor 构建
5go build -mod=vendor

10. 总结

  • go mod init 初始化模块
  • go mod tidy 整理依赖（最常用）
  • go get 添加/升级依赖
  • replace 指令用于本地开发和解决冲突
  • GOPRIVATE 配置私有仓库

思考题： 如果你的项目依赖 A 和 B，而 A 依赖 C v1.0，B 依赖 C v2.0，Go Modules 会如何处理这个冲突？

相关阅读