约 12 分钟6 张卡

Go Modules

Go Modules 是 Go 管理模块身份、依赖关系和依赖版本的机制。它让项目能够声明需要哪些模块，并在构建时确定各模块使用的源码版本。

解释依赖问题时，需要分清“导入哪个包”“选择哪个模块版本”和“从哪里取得源码”。go.mod、go.sum、本地替换与 vendor 分别参与不同环节，把它们统称为锁版本文件，容易在本地联调或干净环境构建时判断错误。本文以 Go 1.22.12 为准。

1. 面试核心

先记住这几条，再读正文

package 是源码组织与编译的单位，module 是共同发布和版本化的一组包。包的导入路径通常由模块路径与模块内子目录组成。卡 · 模块、包与导入路径
go.mod 声明模块路径、Go 版本要求和模块依赖；go.sum 保存依赖内容校验值，不负责决定选哪个版本。卡 · go.mod 与 go.sum
最小版本选择会为同一个模块路径选择满足已加载依赖要求的版本，基本规则是取这些最低要求中的最高版本。它不是从远端自动挑最新版本，也不是选数字最小的版本。卡 · 最低要求中的最高版本
replace 改变当前构建使用的依赖源码。它本身不把模块加入依赖图，依赖库自己的替换规则也不会自动传给使用者。卡 · 替换源码
go.work 可以让多个本地模块共同参与开发，但本地工作区通过，不等于模块独立使用时也能通过。需要检查实际启用的工作区。卡 · 多模块开发
vendor 保存构建所需的依赖包副本；依赖声明变化后要重新生成。模块缓存校验与 vendor 内容检查是不同的事情。卡 · 依赖副本

2. 模块、包与导入路径

卡 · module、package 和 import 路径是什么关系？

模块由根目录中的 go.mod 定义，包含这个目录及其子目录中的包；遇到子目录自己的 go.mod，那里就形成另一个模块边界。一个 Git 仓库可以只有一个模块，也可以包含多个模块，因此仓库、模块和包不是同一个概念。

例如下面的项目结构：

shop/
├── go.mod
├── cmd/shop/main.go
└── internal/price/price.go

go.mod 声明模块路径：

shop/go.mod
module example.com/shop

go 1.22

internal/price/price.go 定义一个包：

package price

func Total(quantity, unitPrice int) int {
    return quantity * unitPrice
}

cmd/shop/main.go 使用包的导入路径：

package main

import (
    "fmt"
    "example.com/shop/internal/price"
)

func main() {
    fmt.Println(price.Total(3, 20))
}

在 shop 目录运行 go run ./cmd/shop，输出 60。模块路径是 example.com/shop，包路径是 example.com/shop/internal/price，代码中使用的包名则是 price。包的导入路径不是本机的绝对磁盘路径。

没有 go.mod 时可以通过 go mod init example.com/shop 初始化。命令创建模块声明，不会替我们生成业务代码，也不意味着模块已经发布到这个域名对应的位置。

同一模块内部导入子包，不需要把每个子包都写进 require。require 面向模块依赖；源码里的 import 面向具体包。包导入还会影响初始化顺序，见 Go 包初始化。

3. go.mod 与 go.sum

卡 · go.mod 和 go.sum 分别负责什么？go.sum 能锁定版本吗？卡 · vendor 中的代码被修改，go mod verify 一定会发现吗？

3.1 依赖声明

go.mod 中的 require 声明所需模块及其最低版本要求。比如应用依赖 example.com/lib v1.2.0，依赖图中的其他要求仍可能把最终选择提高到更高版本。

内容	职责
`module`	当前模块的身份，也是模块内包路径的前缀
`go`	模块要求的 Go 版本，并影响相关语言与模块行为
`toolchain`	主模块对所用工具链的建议，配合工具链选择规则生效
`require`	对其他模块版本的最低要求
`replace`	为当前构建替换依赖源码的位置或版本
`exclude`	在当前主模块中排除指定依赖版本

在本文的 Go 版本下，go 行也是工具链必须满足的最低版本要求；它不是“必须使用这个补丁版编译器”的锁定指令。实际运行哪个工具链，还受 GOTOOLCHAIN、toolchain 和当前工作区影响，应查看 go version。

require 后面的 // indirect 表示该模块没有直接提供被主模块中的包导入的包。它可能通过依赖链被需要，不能仅因为名字叫“间接依赖”就删除。现代模块图裁剪与延迟加载也会让 go.mod 保留这些明确的间接要求。

3.2 内容校验

go.sum 记录模块内容的校验值。记录包括模块路径、版本和校验值；带 /go.mod 的版本项对应模块声明文件，另一类项对应模块内容。一个模块可能出现多个版本的记录，因为解析依赖关系可能需要读取不同版本的 go.mod。

这些记录回答的是“下载到的内容是否与预期校验值一致”，不回答“本次选择哪个版本”。仅看 go.sum 中出现过某个版本，不能断定它正在参与当前构建。应查看模块选择结果，而不是把 go.sum 当成一份独立的依赖锁文件。

go mod verify 检查已下载模块的压缩包及解压目录，是否相对下载时记录的内容发生变化。它与构建命令根据 go.sum 校验下载内容有关联，但职责并不相同；它也不扫描任意本地替换目录或 vendor 文件来证明它们与远端版本一致。

通常应把 go.mod 和 go.sum 一起纳入版本管理。校验成功能帮助确认内容一致性，不代表依赖代码没有缺陷，也不替代业务测试。

4. 版本选择

卡 · 两个依赖分别要求同一模块的 v1.1.0 和 v1.2.0，会选哪个？

4.1 最低要求中的最高版本

最小版本选择（Minimal Version Selection，MVS）根据依赖图中的版本要求，为每个模块路径形成构建所用版本。在没有额外替换、排除等条件时，可以先理解为：同一个路径的多个最低要求，取其中最高的那个。

假设应用同时依赖 A、B：

模块	对 `example.com/lib` 的要求
A v1.0.0	v1.1.0
B v1.0.0	v1.2.0
远端另有的版本	v1.3.0，但当前依赖图没有要求它

构建选择 lib v1.2.0。选择 v1.1.0 无法满足 B 的最低要求，而 v1.3.0 的存在本身不会让构建自动升级。这里“最小”指不无故采用更高版本，不是忽略要求挑最旧版本。

更换 A 或 B 的版本后，它们的依赖要求可能变化，lib 也可能随之变化。手工把主模块里的 lib 降成 v1.1.0，并不能让 B 对 v1.2.0 的要求消失；应检查整条依赖关系。

在没有使用 vendor 模式的模块中，可以用下面几种视角排查：

go list -m all
go mod graph
go mod why -m example.com/lib

go list -m all 显示选择结果，go mod graph 显示模块间的版本要求，go mod why -m 帮助追踪包导入如何让某个模块被需要。图中有多个版本要求，不代表同一个模块路径的多个版本都同时链接进了程序。

4.2 主版本与伪版本

使用模块语义的依赖从 v2 开始，模块路径通常需要带主版本后缀，例如 example.com/lib/v2，源码导入也相应使用这个路径。它与 example.com/lib 是不同模块身份，可以在同一依赖图中共存；不是在原路径上简单把数字换成 v2 就完成迁移。

未按现代模块方式发布的历史版本还有兼容规则，不能把这些例外推广为新模块的发布方式。排查时先看依赖实际声明的模块路径和版本形式。

伪版本是把某个提交表示成可比较的模块版本，形式中包含版本前缀、时间和提交标识。通过提交或分支选择依赖时，Go 工具会把它解析成具体版本；分支名会移动，解析后记录的版本却对应具体源码。不要手工拼接时间和提交片段来制造伪版本。

5. replace 与本地工作区

卡 · replace 能自动添加依赖吗？库中的 replace 会对使用者生效吗？卡 · go.work 中构建成功，为什么关闭工作区后可能失败？

5.1 替换源码

本地联调时，可以让主模块改用一个本地目录中的依赖。例如下面是一份独立应用的 go.mod，../lib-local 也包含自己的 go.mod：

app/go.mod
module example.com/app

go 1.22

require example.com/lib v1.2.0

replace example.com/lib => ../lib-local

源码仍然导入 example.com/lib，只是实际文件来自替换目录。这里没有指定左侧版本，因此匹配这个模块路径的所有所需版本；也可以写明某个版本，只替换它。

replace 只改变查到依赖之后使用哪份源码，不会凭空增加依赖。只写替换、不存在对应 require 时，不能认为这个模块已经加入构建。

替换规则由主模块控制。某个库的 go.mod 写了本地 replace，当另一个项目把这个库当依赖时，不会自动沿用库作者磁盘上的替换。发布前需要确认正常版本依赖本身成立，否则会出现“在库目录里能运行，别人引用就失败”的情况。

本地目录替换也意味着构建受该目录当前内容影响。路径存在但源码不同，同一个 require 版本文字仍可能构建出不同程序。要复现结果，除了版本声明，还要记录实际替换内容和构建环境。

5.2 多模块开发

工作区通过 go.work 把多个本地模块一起作为开发时的主模块。例如应用和正在修改的库需要同时联调，可以在它们的共同父目录创建工作区，并把两个模块目录加入 use 列表。

它可以减少临时修改各模块 go.mod 的需求，但也会影响本次版本选择和源码来源。应用在工作区中可能使用本地库，离开工作区则使用自己声明的已发布版本；两次结果不同，不一定是模块缓存失效。

先用 go env GOWORK 确认当前工作区。需要检查模块独立使用的状态时，可以在该模块目录执行：

GOWORK=off go test ./...

这只对当前命令关闭工作区，并不删除 go.work。项目是否提交工作区文件取决于协作方式，但每个独立发布的模块都应检查自己的依赖是否完整。

6. vendor 与依赖维护

卡 · vendor 中的代码被修改，go mod verify 一定会发现吗？

6.1 依赖副本

vendor 目录保存主模块构建和测试所需的依赖包副本，并通过 vendor/modules.txt 记录相关模块信息。它不是把所有下载过的模块缓存原样复制一份。

在单模块环境中，可以执行：

go mod vendor
go test -mod=vendor ./...

在本文的工具链下，主模块 go 行不低于 1.14、且存在符合条件的 vendor 目录时，构建默认可以进入 vendor 模式；显式指定 -mod=vendor 可以让验证意图更清楚。

go.mod 与 vendor/modules.txt 不一致时，构建可能报告 inconsistent vendoring。应该根据新的依赖声明重新生成副本，不能只改清单中的版本文字来伪造一致。

go mod vendor 会重建这个目录。直接修改 vendor 中的依赖代码，既可能在重建时丢失，也不会被 go mod verify 当成模块缓存篡改来检查。需要长期修补依赖时，应有明确的补丁或替换来源，并验证重新生成得到的内容。

6.2 常用维护命令

命令	主要作用
`go mod tidy`	按源码和测试所需包整理依赖声明与校验记录，补充缺少内容、移除不再需要的内容
`go get 模块@版本`	调整依赖版本要求，并处理相关依赖关系
`go mod download`	下载依赖到模块缓存，不等于执行项目测试
`go mod verify`	检查已下载模块的缓存内容是否被修改
`go list -m all`	查看所选模块版本；排查时同时注意当前是否在 vendor 模式