在早期的 Go 语言版本中,管理项目代码有一条很不方便的规定:所有 Go 源代码都必须放在一个固定的 GOPATH/src 文件夹下,而且很难准确指定第三方包的版本号。
为了解决这个痛点,Go 官方推出了 Go Modules(模块管理)。使用 Go Modules 之后,我们不仅可以在电脑的任意文件夹下创建项目,还能像 Python 的 pip 或前端的 npm 一样,通过几条简单的命令下载、升级和清理第三方开源包。
平时使用 Go Modules 管理项目时,最常用的命令如下表所示。
| 命令 | 说明 |
|---|---|
| go mod init | 初始化模块并生成 go.mod |
| go get | 下载、切换版本或升级第三方包 |
| go mod tidy | 扫描源码,补齐缺失并清理多余依赖 |
| go mod download | 按 go.mod 批量下载依赖包 |
| go clean -modcache | 清空本地共享模块缓存 |
初始化模块:go mod init
在 Go 语言中,一个代码包用来管理单个文件夹下的源码,而 “模块(Module)” 则对应整个项目,里面可以包含一个或多个包。每个模块根目录下的 go.mod 文件就像是项目的 “依赖清单”,用来记录模块名、Go 版本和第三方依赖。
每当我们新建一个 Go 项目文件夹时,首先要在终端进入该文件夹,执行 go mod init 命令来初始化模块。
语法:
go mod init 模块名说明:
go mod init 后面跟的 “模块名” 是当前项目的唯一标识。如果是平时本地练习或公司内部不对外公开的项目,我们直接起一个简短的英文名就可以了,比如 myproject、hello 或 shop,一般与项目文件夹的名字保持一致。
如果这个项目以后准备开源发布到网上供别人下载使用,那么模块名通常会写成代码仓库的网址路径,比如 github.com/username/project。
示例 1:初始化 myproject 模块
# 1. 新建项目文件夹并进入该目录
mkdir myproject
cd myproject
# 2. 初始化名为 myproject 的模块
go mod init myproject运行结果如下。
go: creating new go.mod: module myproject分析:
当终端输出 creating new go.mod 提示时,就说明模块初始化成功了。此时打开 myproject 文件夹,可以看到里面自动生成了一个名为 go.mod 的文本文件,初始内容如下:
module myproject
go 1.24.0在这个初始的 go.mod 文件中,第 1 行 module myproject 声明了当前项目的模块名,后面导入自定义包时就要以它开头。第 2 行 go 1.24.0 记录了当前使用的 Go 版本,实际版本号以小伙伴们本地安装的为准。
安装第三方包:go get
初始化好 go.mod 文件之后,如果我们在写代码时需要用到生成唯一 ID、连接数据库等社区开源包,就可以在项目根目录下使用 go get 命令将其下载到项目中。
平时如果想查找某个功能的第三方包及其导入路径,我们可以直接前往 Go 官方包检索站 pkg.go.dev 搜索。
语法:
go get 包路径
go get 包路径@版本号
go get -u 包路径说明:
上面这 3 种常见写法的用途如下:
- 安装最新稳定版:直接执行
go get 包路径,等价于在末尾加上@latest,Go 会自动拉取该包最新发布的稳定版本。 - 安装指定历史版本:在包路径末尾加上
@v版本号,比如go get github.com/google/uuid@v1.5.0。 - 升级已安装的包:加上
-u参数执行go get -u 包路径,可以将项目中已安装的第三方包升级到最新版本。
注意: 由于 Go 默认的模块服务器位于海外,国内网络直接执行 go get 时很容易卡住并报连接超时。建议小伙伴们先在终端执行 go env -w GOPROXY="https://goproxy.cn,direct" 切换国内下载源,再运行下面示例。更多备用镜像与详细配置可以看 GOPROXY 镜像源。
示例 2:下载并调用第三方包
我们以 Google 开源的生成唯一 ID 工具库 uuid 为例,先在 myproject 项目根目录下执行以下命令下载该包:
go get github.com/google/uuid下载完成后,终端输出结果如下。
go: added github.com/google/uuid v1.6.0接着我们在 myproject 目录下新建 main.go 文件,通过 import 导入刚才下载的第三方包并调用:
package main
import (
"fmt"
"github.com/google/uuid"
)
func main() {
id := uuid.NewString()
fmt.Println(id)
}在终端执行 go run . 运行程序,运行结果如下。
f47ac10b-58cc-4372-a567-0e02b2c3d479分析:
uuid.NewString() 每次都会随机生成一个全球唯一的字符串编号,小伙伴们本地运行看到的字符会和上面不一样,只要格式类似就说明调用成功了。
执行完 go get 后,为什么 myproject 文件夹里并没有多出 uuid 的源码呢?这是因为 Go 不会把第三方包塞进项目目录,而是统一保存在本地缓存目录 GOPATH/pkg/mod 中,供电脑上的所有 Go 项目共享(如下图所示)。

此时打开项目的 go.mod 文件,会看到里面自动多出了一行 require 依赖记录:
module myproject
go 1.24.0
require github.com/google/uuid v1.6.0如果安装的第三方包自身还用到了其他底层包,go.mod 里也会一并列出,并在行尾自动标上 // indirect(间接依赖)注释。这些记录同样由 Go 自动维护,小伙伴们不需要手动删改。
此外,项目根目录下还会自动生成一个名为 go.sum 的文件。go.sum 里面记录着每个第三方包版本的哈希校验码,用来确保以后每次构建项目时,下载到的依赖包内容都没有被篡改过。平时开发时,go.sum 完全由 Go 自动维护,我们不需要手动修改它。
如果后续需要把 uuid 切换到旧版本,或者再升级回最新版,我们直接在项目根目录下执行对应命令,go.mod 里的版本号就会跟着自动更新:
# 切换为指定历史版本 v1.5.0
go get github.com/google/uuid@v1.5.0
# 升级回最新稳定版本
go get -u github.com/google/uuid自动整理依赖:go mod tidy
既然已经有 go get 了,为什么还需要 go mod tidy 呢?
在日常写项目时,我们经常会直接在 .go 代码里先写好 import "第三方包路径",或者把不再使用的第三方包从代码里删掉。这时只需要执行一行 go mod tidy,Go 就会自动帮我们把依赖清单 “多退少补” 整理干净。其中,tidy 是英文 “整理” 的意思。
语法:
go mod tidy说明:
在项目根目录下执行 go mod tidy 时,Go 会扫描当前项目中的所有 .go 源文件,并自动完成以下 2 件事:
- 自动补齐缺失依赖:把代码里
import用到了、但还没记录进go.mod的包自动下载下来,并写入go.mod。 - 自动清理多余依赖:把代码里已经删掉、不再使用的第三方包从
go.mod和go.sum中移除。
示例 3:自动补齐缺失的依赖
在前面示例 2 的 myproject 项目中,如果我们把 go.mod 里的 require 那一行手动删掉,只保留 main.go 里的代码,此时直接执行 go run . 会提示缺少依赖记录。这时我们只需在 myproject 根目录下执行以下命令:
go mod tidy运行结果如下。
go: finding module for package github.com/google/uuid
go: found github.com/google/uuid in github.com/google/uuid v1.6.0分析:
go mod tidy 扫描代码后发现 main.go 用到了 github.com/google/uuid,于是自动帮我们补齐依赖,并同步更新了 go.mod 和 go.sum 文件。之后再执行 go run .,程序就能正常运行了。
反过来,如果我们把 main.go 里调用 uuid 包的代码删掉,只留一句普通的打印语句。再次执行 go mod tidy 时,它又会自动把那条多余的 require 记录从 go.mod 中清理掉,小伙伴们可以在本地动手试一下。
平时从网上下载别人的 Go 开源项目时,代码包里一般只包含源码和 go.mod 文件。拿到项目后,我们只要在项目根目录下执行一次 go mod tidy 或 go mod download,所需的全部第三方包就会按清单记录的版本号一次性拉取齐全。
常见问题
1. 不再使用的第三方包,应该怎么从项目中卸载?
在 Go Modules 中,我们不需要专门记忆卸载命令。平时只要先把 .go 源代码里对应的 import 语句和调用代码删掉,然后在项目根目录下执行一次 go mod tidy,Go 就会自动把不再使用的包从 go.mod 和 go.sum 清单中移除。
至于缓存在本地 GOPATH/pkg/mod 目录里的历史包文件,留着可以加快其他项目的构建速度,一般不需要手动删除。如果确实想彻底清空本地缓存,执行 go clean -modcache 就可以了。
2. 使用 Git 管理项目时,go.mod 和 go.sum 都需要提交到代码仓库吗?
是的,两个文件都应该一起提交到 Git 仓库中。go.mod 用来锁定项目依赖的具体版本号,而 go.sum 用来校验依赖包的内容是否完整可靠。把它们一起提交上去,团队里的其他成员拉取代码后,才能还原出完全一致的运行环境。
