Go Modules
什么是模块
Go Modules 是 Go 语言的官方依赖管理工具，自 Go 1.11 引入，Go 1.16 成为默认的依赖管理模式。解决版本控制、依赖隔离、可重复构建等问题。
核心概念：
- 模块（Module）：包含 go.mod 文件的目录树，定义了模块路径、Go 版本要求和依赖关系
- 版本（Version）：遵循语义化版本控制（Semantic Versioning），格式为 vMAJOR.MINOR.PATCH
- 依赖图（Dependency Graph）：模块及其所有传递依赖的层次结构，由 Go 工具自动解析维护
为什么需要 Go Modules
GOPATH 模式的局限：
- 所有项目必须放在 GOPATH 目录下
- 无法精确控制依赖版本
- 多个项目可能使用同一依赖的不同版本（依赖冲突）
- 难以确保不同环境下构建一致
GOPATH vs Go Modules 对比：
| 特性 | GOPATH 模式 | Go Modules |
|---|---|---|
| 项目位置限制 | 必须放在 GOPATH 下 | 任意位置均可 |
| 版本控制 | 有限支持 | 完整的语义化版本控制 |
| 依赖隔离 | 全局共享 | 项目级隔离 |
| 可重复构建 | 困难 | 自动保障 |
| 离线工作 | 不支持 | 支持本地缓存 |
go.mod 文件结构
go.mod 是模块的定义文件，主要包含 module / go / require / replace / exclude 五部分：
go.mod:
module example.com/mymodule // 模块路径
go 1.21 // Go 版本要求
require (
github.com/gin-gonic/gin v1.9.1
golang.org/x/text v0.12.0
)
replace golang.org/x/text => ../local/text // 本地替换
exclude github.com/old/module v1.0.0 // 排除特定版本
指令说明：
| 指令 | 作用 |
|---|---|
| module | 声明模块路径 |
| go | 指定模块要求的 Go 版本 |
| require | 声明依赖及其版本 |
| replace | 替换依赖（本地路径/fork仓库/不同版本） |
| exclude | 排除指定版本的依赖 |
go.sum 文件
go.sum 记录依赖模块的加密哈希值，用于验证模块内容的完整性：
github.com/bytedance/sonic v1.9.1 h1:ei0tVql02GmiYGRCTUcI6g...
github.com/bytedance/sonic v1.9.1/go.mod h1:iZcSUejdk5C4OW...
基本命令
初始化模块：
创建新模块
go mod init example.com/myproject
在现有项目中初始化
cd /path/to/project go mod init
依赖管理：
添加依赖（自动选择最新版本）
go get github.com/gin-gonic/gin
添加特定版本
go get github.com/gin-gonic/gin@v1.9.1
更新到最新版本
go get -u github.com/gin-gonic/gin
更新所有依赖
go get -u all
下载依赖到本地缓存
go mod download
整理 go.mod 文件（添加缺失、移除未使用的依赖）
go mod tidy
依赖查询：
查看所有依赖
go list -m all
查看特定依赖的可用版本
go list -m -versions github.com/gin-gonic/gin
查看为什么需要某个依赖
go mod why github.com/gin-gonic/gin
实际工作流程
新项目初始化：
创建项目目录
mkdir myproject && cd myproject
初始化模块
go mod init github.com/username/myproject
编写代码并导入依赖，然后运行以下命令自动处理依赖
go mod tidy
间接依赖由 Go 工具自动管理，不用手写。
版本选择：Go Modules 使用最小版本选择（MVS）算法自动解决依赖版本冲突。
GOPROXY 国内镜像
依赖下载失败时设置代理：
go env -w GOPROXY=https://goproxy.cn,direct
清理缓存并重试：
go clean -modcache go mod download
常用国内镜像：
| 镜像 | 地址 |
|---|---|
| 阿里云 | https://mirrors.aliyun.com/goproxy |
| 微软 | https://goproxy.io |
| 七牛云 | https://goproxy.cn |
高级特性
替换依赖（replace）：
// 用本地路径替换远程依赖 replace github.com/some/dependency => ../local/dependency
// 用 fork 仓库替换 replace github.com/some/dependency => github.com/myfork/dependency v1.0.0
排除特定版本（exclude）：
exclude ( github.com/problematic/module v1.0.0 github.com/another/badmodule v2.1.0 )
示例：创建第一个模块
mkdir hello-world && cd hello-world go mod init example.com/hello
package main
import (
"fmt"
"rsc.io/quote"
)
func main() {
fmt.Println(quote.Hello())
}运行并观察依赖管理：
go run main.go go mod tidy cat go.mod
常用排查命令
| 场景 | 命令 |
|---|---|
| 查看依赖图 | go mod graph |
| 分析版本冲突原因 | go mod why -m conflicting/package |
| 检查未使用依赖 | go mod tidy -v |
| 校验 go.mod 与 go.sum 一致 | go mod verify |
| 创建 vendor 目录（可选，锁定版本） | go mod vendor |