wonder/cs-note

Fork 0

Files

T

wonder 7ce9b83218 vault backup: 2026-06-07 12:14:39

2026-06-07 12:14:39 +08:00

4.7 KiB

Raw Blame History

tags, create time

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`	私有仓库域名	按需设置

# 国内开发者推荐配置
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：私有仓库

对于不在公共代理中的私有仓库：

go env -w GOPRIVATE="github.com/myorg/*,git.internal.company.com"

[!tip] 💡 通配符支持 github.com/myorg/* 会匹配 myorg 下的所有子仓库。

go.mod 文件结构

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：

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] 💡 日常开发工作流

go get github.com/example/pkg@latest   # 添加/升级依赖
go mod tidy                             # 清理
go build                                # 编译（自动检查一致性）

版本选择规则

情况	行为
有语义化标签（v1.2.3）	取最大主版本标签
无标签	取 main 分支最新 commit，生成伪版本号
伪版本号	`v0.0.0-yyyyMMddHHmmss-abcdef123456`

replace 的使用场景

当公共代理不可用时，用 replace 指向镜像或本地路径：

replace golang.org/x/image => github.com/golang/image v0.18.0

或者指向本地开发路径：

replace mycompany/internal/pkg => ../internal/pkg

[!info] ℹ️ replace 不影响 import 语句代码中仍然写 import "golang.org/x/image"，Go 会自动识别 replace 映射到实际路径。

4.7 KiB Raw Blame History Unescape Escape