Go Modules - 模块管理

Go Modules 是 Go 的依赖管理系统，从 Go 1.11 引入，Go 1.13+ 成为标准。掌握 Modules 是管理 Go 项目依赖的基础。

初始化模块

📝 创建模块

# 初始化新模块
go mod init github.com/user/project

# 生成的 go.mod:
module github.com/user/project

go 1.26

# 添加依赖
go get github.com/gin-gonic/gin

# 整理依赖
go mod tidy

# 查看依赖
go list -m all

# 更新依赖
go get -u github.com/gin-gonic/gin

# 降级依赖
go get github.com/gin-gonic/gin@v1.9.0

# 清理未使用依赖
go mod tidy

go.mod 文件

📖 go.mod 格式

module github.com/user/myapp

go 1.26

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/go-redis/redis/v8 v8.11.5
)

require (
    github.com/gin-contrib/sse v0.1.0 // indirect
    github.com/go-playground/validator/v10 v10.14.0 // indirect
)

replace github.com/old/package => github.com/new/package v1.0.0

exclude github.com/bad/package v1.0.0

// 字段说明:
// module: 模块路径
// go: Go 版本
// require: 依赖列表
// indirect: 间接依赖
// replace: 替换依赖
// exclude: 排除版本

常用命令

📝 Modules 命令

# 初始化
go mod init [module-path]

# 下载依赖
go mod download

# 整理依赖 (添加缺失，删除未用)
go mod tidy

# 验证依赖
go mod verify

# 查看依赖
go list -m all                 # 所有依赖
go list -m -versions [pkg]     # 可用版本
go list -m -json [pkg]         # 详细信息

# 编辑 go.mod
go mod edit -require=pkg@v1.0.0
go mod edit -droprequire=pkg
go mod edit -replace=old=new

# 缓存管理
go clean -modcache             # 清理缓存
go env GOMODCACHE              # 缓存位置

# 构建
go build -mod=readonly         # 只读模式
go build -mod=vendor           # 使用 vendor

版本管理

📖 语义化版本

# 版本格式
v1.2.3  # 主版本。次版本。修订版本

# 预发布版本
v1.2.3-beta.1
v1.2.3-rc.1

# 伪版本 (从 commit 生成)
v0.0.0-20240101123456-abcdef123456

# 版本选择
go get pkg@latest              # 最新版
go get pkg@upgrade             # 最新兼容版
go get pkg@patch               # 最新补丁版
go get pkg@v1.2.3              # 指定版本
go get pkg@abcdef123456        # 指定 commit

最佳实践

✅ Modules 使用建议

  • 提交 go.sum: 确保依赖完整性
  • 定期 tidy: 保持依赖干净
  • 锁定版本: 生产环境锁定依赖版本
  • 检查更新: 定期检查安全更新
  • 使用 proxy: 配置 GOPROXY 加速下载

📖 配置代理

# 设置 GOPROXY
go env -w GOPROXY=https://goproxy.cn,direct

# 常用代理:
# https://goproxy.io (全球)
# https://goproxy.cn (中国)
# https://mirrors.aliyun.com/goproxy/ (阿里云)