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

1. 什么是 Go Modules？

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

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

2. 初始化模块

2.1 创建新模块

# 创建项目目录
mkdir myproject
cd myproject

# 初始化模块
# 模块路径通常是代码仓库地址
go mod init github.com/username/myproject

这会生成 go.mod 文件：

module github.com/username/myproject

go 1.21

2.2 go.mod 文件结构

module github.com/username/myproject  // 模块路径

go 1.21  // Go 版本

require (
    github.com/gin-gonic/gin v1.9.1  // 直接依赖
    gorm.io/gorm v1.25.5
)

require (
    github.com/gin-contrib/sse v0.1.0  // 间接依赖（由 gin 引入）
    // ... 更多间接依赖
) // indirect

exclude (
    github.com/some/package v1.2.3  // 排除某个版本
)

replace (
    github.com/old/package => github.com/new/package v1.0.0  // 替换依赖
)

3. 常用命令

3.1 添加依赖

# 方法一：直接在代码中 import，然后运行
go mod tidy

# 方法二：手动添加
go get github.com/gin-gonic/gin@v1.9.1

# 获取最新版本
go get github.com/gin-gonic/gin@latest

# 获取特定版本
go get github.com/gin-gonic/gin@v1.8.0

# 获取某个 commit
go get github.com/gin-gonic/gin@abc1234

3.2 go mod tidy

最常用的命令，它会：

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

3.3 下载依赖

# 下载所有依赖到本地缓存
go mod download

# 查看依赖存放位置
go env GOMODCACHE
# 通常是 ~/go/pkg/mod

3.4 查看依赖

# 查看所有依赖（包括间接依赖）
go list -m all

# 查看依赖树
go mod graph

# 查看某个包为什么被引入
go mod why github.com/some/package

3.5 升级依赖

# 升级所有依赖到最新的小版本
go get -u ./...

# 升级到最新的主版本（可能有破坏性变更）
go get -u=patch ./...

# 升级特定包
go get -u github.com/gin-gonic/gin

4. 版本管理

4.1 语义化版本 (Semantic Versioning)

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

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

4.2 主版本升级

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

// v1 版本
import "github.com/some/package"

// v2 版本（路径变化！）
import "github.com/some/package/v2"

5. replace 指令

5.1 替换为本地路径

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

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

5.2 替换为 fork 版本

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

5.3 解决依赖冲突

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

6. 私有仓库配置

6.1 配置 GOPRIVATE

# 设置私有仓库前缀
go env -w GOPRIVATE=github.com/yourcompany/*

# 多个前缀用逗号分隔
go env -w GOPRIVATE=github.com/company1/*,gitlab.com/company2/*

6.2 配置 Git 认证

# 方法一：使用 SSH
git config --global url."git@github.com:".insteadOf "https://github.com/"

# 方法二：使用 Token
git config --global url."https://username:token@github.com/".insteadOf "https://github.com/"

6.3 配置 GOPROXY

# 使用国内代理（加速下载）
go env -w GOPROXY=https://goproxy.cn,direct

# 跳过代理直接访问私有仓库
go 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 依赖下载失败

# 清理缓存
go clean -modcache

# 使用代理
go env -w GOPROXY=https://goproxy.cn,direct

9.2 版本冲突

# 查看冲突
go mod graph | grep package-name

# 使用 replace 强制指定版本

9.3 vendor 目录

# 将依赖复制到 vendor 目录（可选）
go mod vendor

# 使用 vendor 构建
go 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 会如何处理这个冲突？

相关阅读