67. go.mod 与模块基础

本节目标：看懂 go.mod 文件的每一行，学会创建模块，理解 go directive 和 GOTOOLCHAIN 的版本管理机制。

什么是模块

模块（Module）是 Go 的代码组织单位。一个模块包含一个或多个包，通过 go.mod 文件定义。模块模式下，项目根目录有 go.mod，里面声明了模块路径和依赖。

Go 1.11 引入了模块模式，Go 1.16 起默认启用（GO111MODULE 默认值改为 on），老的 GOPATH 模式已经退出历史舞台。

创建模块

用 go mod init 创建：

mkdir myproject
cd myproject
go mod init example.com/myproject

这会生成一个 go.mod 文件：

module example.com/myproject

go 1.25.0

Note

Go 1.26 起，go mod init 默认写入更低的 go 版本。用 1.26 工具链会生成 go 1.25.0，鼓励兼容当前支持的版本。想指定版本可以接着跑 go get go@1.26.0。

module path

模块路径是模块的唯一标识，也是别人 import 你代码时的前缀：

module example.com/myproject

如果项目在 GitHub 上，路径就是 github.com/你的用户名/项目名。这个路径要和代码仓库的地址对应，因为别人 go get 时会按这个路径去下载。

模块路径: github.com/user/repo
导入路径: github.com/user/repo/subpackage

go directive

go 行声明这个模块需要的最低 Go 版本：

go 1.25.0

它的作用不止「最低版本要求」。Go 1.21 起，go 行还决定语言语义：比如 go 1.22 及以上的模块，for 循环变量每次迭代新建；低于 1.22 的模块保持旧行为。

Tip

把 go 行设成你实际在用的版本就行，别故意写低版本「兼容」。低版本会限制你能用的语言特性，而且工具链会自动帮你兼容旧环境。

toolchain 指令

Go 1.21 引入了 toolchain 指令：

module example.com/myproject

go 1.25.0

toolchain go1.26.0

go 行：最低要求，低于这个版本不能用
toolchain 行：建议使用的工具链版本，可以比 go 高

当你用 Go 1.26 跑一个 go 1.23 的项目，go 命令会自动下载并切换到合适的工具链，不用你手动装。

GOTOOLCHAIN

环境变量 GOTOOLCHAIN 控制工具链行为：

go env GOTOOLCHAIN          # 查看当前值
go env -w GOTOOLCHAIN=auto  # 设置

常用值：

auto（默认）：按 go.mod 里的 go/toolchain 自动选择，必要时下载
go1.26.0：固定用某个版本
local：只用本地安装的版本，不自动切换

Warning

如果你团队锁版本，可以设 GOTOOLCHAIN=local 避免意外下载。但一般保持 auto 最省心。

go.mod 完整结构

一个真实的 go.mod 长这样：

module example.com/myproject

go 1.25.0

toolchain go1.26.0

require (
	example.com/other v1.2.3
	github.com/gin-gonic/gin v1.9.1
)

require (
	github.com/json-iterator/go v1.1.12 // indirect
)

replace example.com/other => ../other // 本地替换

exclude example.com/badpkg v1.0.0      // 排除有问题的版本

各指令含义：

指令	作用
`module`	模块路径
`go`	最低 Go 版本
`toolchain`	建议工具链版本
`require`	依赖及版本
`replace`	替换依赖（用本地或其他源）
`exclude`	排除某个版本
`retract`	撤回自己发布的某个版本

indirect 是什么

// indirect 注释表示这个依赖是被间接引入的（你的代码没直接 import 它，是你依赖的依赖用了它）：

require (
	github.com/json-iterator/go v1.1.12 // indirect
)

go mod tidy 会自动管理这些标注，你一般不用手动改。

常用命令

go mod init <path>     # 创建新模块
go mod tidy            # 整理依赖（加缺失、删多余）
go mod download        # 下载依赖到缓存
go mod verify          # 校验依赖完整性
go mod why <pkg>       # 查看为什么需要这个依赖
go mod graph           # 打印依赖图
cat go.mod             # 直接看文件

Tip

go mod tidy 是最常用的命令。每次改完代码加新依赖，跑一遍 go mod tidy 让 go.mod 和 go.sum 保持整洁。

小结

go mod init 创建模块，生成 go.mod
module 行是模块路径，要和仓库地址对应
go 行是最低版本，也决定语言语义
toolchain 行是建议工具链，可自动切换下载
require 列依赖，// indirect 标记间接依赖
go mod tidy 整理依赖，最常用

下一节讲怎么添加和管理依赖。