158 lines
4.7 KiB
Markdown
158 lines
4.7 KiB
Markdown
---
|
||
tags: [go, golang, go基础语法, modules, go modules, 依赖管理]
|
||
create time: 2026-06-07 15:00
|
||
---
|
||
|
||
# Go 语言依赖管理
|
||
|
||
## 概述
|
||
|
||
Go Modules 是 Go 1.11+ 引入的官方依赖管理方案。本文讲解 go.mod/go.sum 的核心结构、常用命令和关键环境变量的配置。
|
||
|
||
## 正文
|
||
|
||
### 为什么 Go 需要 Modules？
|
||
|
||
在 Modules 出现之前，Go 依赖 `GOPATH` 管理——所有代码必须放在 `$GOPATH/src` 下。这导致：
|
||
- 项目路径与代码仓库路径不一致
|
||
- 依赖版本无法锁定
|
||
- 多项目间依赖冲突
|
||
|
||
Go Modules 让每个项目**自包含**其依赖信息，不再依赖 GOPATH。
|
||
|
||
### 核心环境变量
|
||
|
||
| 变量 | 用途 | 推荐值 |
|
||
|------|------|--------|
|
||
| `GO111MODULE` | 开关（auto/on/off） | `on`（Go 1.14+ 默认） |
|
||
| `GOPROXY` | 模块代理地址 | `https://goproxy.cn,direct`（国内） |
|
||
| `GOSUMDB` | 校验数据库 | `sum.golang.org`（默认） |
|
||
| `GOPRIVATE` | 私有仓库域名 | 按需设置 |
|
||
|
||
```bash
|
||
# 国内开发者推荐配置
|
||
go env -w GO111MODULE=on
|
||
go env -w GOPROXY=https://goproxy.cn,direct
|
||
```
|
||
|
||
> [!info] ℹ️ `direct` 的含义
|
||
> `GOPROXY=https://goproxy.cn,direct` 表示先从 goproxy.cn 拉取，如果返回 404/410，则回源到原始仓库（如 GitHub）。
|
||
|
||
### GOPRIVATE：私有仓库
|
||
|
||
对于不在公共代理中的私有仓库：
|
||
|
||
```bash
|
||
go env -w GOPRIVATE="github.com/myorg/*,git.internal.company.com"
|
||
```
|
||
|
||
> [!tip] 💡 通配符支持
|
||
> `github.com/myorg/*` 会匹配 `myorg` 下的所有子仓库。
|
||
|
||
### go.mod 文件结构
|
||
|
||
```go
|
||
module example.com/myproject // 模块路径（import 的基础路径）
|
||
|
||
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 // indirect
|
||
)
|
||
|
||
replace ( // 替换某个依赖
|
||
golang.org/x/image => github.com/golang/image v0.18.0
|
||
)
|
||
|
||
retract v0.2.0 // 撤回不推荐的版本
|
||
```
|
||
|
||
> [!note] 📝 关键字段说明
|
||
|
||
| 字段 | 作用 |
|
||
|------|------|
|
||
| `module` | 当前模块的唯一路径，import 语句以此为前缀 |
|
||
| `go` | 声明兼容的 Go 最低版本 |
|
||
| `require` | 依赖列表，分直接和间接两类 |
|
||
| `replace` | 将 A 替换为 B（可用于本地开发或镜像） |
|
||
| `exclude` | 排除某个特定版本（Go 1.16+） |
|
||
| `retract` | 声明某版本不应被使用（Go 1.16+） |
|
||
|
||
### indirect 标记
|
||
|
||
当你的项目依赖 A，A 又依赖 B，但 A 的 go.mod 缺少 B 时，你的项目中 B 会被标记为 `// indirect`。
|
||
|
||
执行 `go mod tidy` 后，无用的 indirect 依赖会被移除。
|
||
|
||
### +incompatible 标记
|
||
|
||
语义化版本要求：v2+ 的模块路径需包含 `/v2`。如果作者忘了改路径，版本号后面会加上 `+incompatible`：
|
||
|
||
```go
|
||
require github.com/pkg/errors v0.9.1+incompatible
|
||
```
|
||
|
||
功能上与普通版本无异，只是提醒开发者这个模块没有遵循语义化版本规范。
|
||
|
||
### go.sum：安全校验
|
||
|
||
`go.sum` 记录每个依赖的哈希值，确保下载的内容未被篡改：
|
||
|
||
```
|
||
github.com/spf13/cast v1.4.1 h1:s0hze+J0196ZfEMTs80N7UlFt0BDuQ7Q+JDnHiMWKdA=
|
||
github.com/spf13/cast v1.4.1/go.mod h1:Qx5cxh0v+4UWYiBimWS+eyWzqEqk=
|
||
```
|
||
|
||
> [!warning] ⚠️ 不要手动编辑 go.sum
|
||
> 它由 Go 工具链自动生成和维护。
|
||
|
||
### 常用命令速查
|
||
|
||
| 命令 | 作用 |
|
||
|------|------|
|
||
| `go mod init module/path` | 初始化新模块 |
|
||
| `go get package@version` | 添加/更新依赖 |
|
||
| `go mod tidy` | 清理无用依赖，补充缺失依赖 |
|
||
| `go mod download` | 下载依赖到本地缓存 |
|
||
| `go mod graph` | 打印依赖图 |
|
||
| `go mod vendor` | 导出依赖到 vendor/ 目录 |
|
||
| `go mod verify` | 校验依赖完整性 |
|
||
| `go clean -modcache` | 清除模块缓存 |
|
||
|
||
> [!tip] 💡 日常开发工作流
|
||
> ```bash
|
||
> go get github.com/example/pkg@latest # 添加/升级依赖
|
||
> go mod tidy # 清理
|
||
> go build # 编译（自动检查一致性）
|
||
> ```
|
||
|
||
### 版本选择规则
|
||
|
||
| 情况 | 行为 |
|
||
|------|------|
|
||
| 有语义化标签（v1.2.3） | 取最大主版本标签 |
|
||
| 无标签 | 取 main 分支最新 commit，生成伪版本号 |
|
||
| 伪版本号 | `v0.0.0-yyyyMMddHHmmss-abcdef123456` |
|
||
|
||
### replace 的使用场景
|
||
|
||
当公共代理不可用时，用 replace 指向镜像或本地路径：
|
||
|
||
```go
|
||
replace golang.org/x/image => github.com/golang/image v0.18.0
|
||
```
|
||
|
||
或者指向本地开发路径：
|
||
|
||
```go
|
||
replace mycompany/internal/pkg => ../internal/pkg
|
||
```
|
||
|
||
> [!info] ℹ️ replace 不影响 import 语句
|
||
> 代码中仍然写 `import "golang.org/x/image"`，Go 会自动识别 replace 映射到实际路径。
|