目录
Go 模块管理详解:go.mod、go.work 从入门到实际项目应用
Go 语言的模块管理主要涉及三个文件:
- go.mod:管理单个模块的身份、Go 版本和依赖。
- go.sum:记录依赖校验信息,保证依赖内容的完整性。
- go.work:管理多个本地模块,方便多个项目之间联合开发、调试。
从 Go 1.18 开始,Go 正式支持多模块工作区(Workspace)。截至 2026 年 11 月,Go 1.27 已发布,下面的基础功能仍适用。
本文将以一个 国际物流业务系统 为例,逐步演示这三个文件的作用、语法、使用命令和实际开发方案。
一、先理解三个核心概念
1. Package、Module、Workspace 有什么区别?
这是理解 Go 模块管理最重要的基础。

Package(包)
Go 代码组织的基本单位,通常一个目录对应一个包。
例如:
crm/ ├── handler/ # handler 包 ├── service/ # service 包 ├── repository/ # repository 包 └── main.go # main 包
Module(模块)
一组相关 Go 包的集合,通过 go.mod 声明模块名称和依赖版本。
例如:
crm/ ├── go.mod # 定义整个 crm 模块 ├── main.go ├── handler/ └── service/
Workspace(工作区)
多个 Go 模块的本地协作环境,由 go.work 定义。
例如:
sps/
├── go.work
├── crm/
│ └── go.mod
├── oms/
│ └── go.mod
└── common/
└── go.mod
这里有三个独立模块,但它们可以通过一个工作区协同开发。
2. go.mod 和 go.work 的核心区别
| 对比维度 | go.mod | go.work |
|---|---|---|
| 管理对象 | 一个 Go 模块 | 多个本地 Go 模块 |
| 主要用途 | 模块声明、依赖管理 | 跨模块开发和调试 |
| 必须存在吗 | 模块项目通常必须有 | 不必须 |
| 管理依赖版本 | 是,require | 不直接声明 require |
| 本地路径引用 | replace | use、replace |
| 影响范围 | 单个模块 | 当前工作区 |
| 是否建议提交 Git | 是 | 根据团队开发方式决定 |
| 能否单独构建部署 | 模块可以独立构建 | 工作区本身不是部署单元 |
可以把它们简单理解为:
go.mod 解决“我的项目依赖谁”,go.work 解决“我本地同时开发哪几个项目”。
重要的是:go.work 并不取代 go.mod。即使使用工作区,每个模块仍然需要独立维护自己的依赖关系。
二、go.mod 详细讲解
1. 创建一个 Go 模块
假设要开发一个 SPS 的 CRM 系统。
# 创建项目 mkdir sps-crm cd sps-crm # 初始化 Go Module go mod init example.com/sps/crm
执行后,会生成:
sps-crm/ └── go.mod
go.mod 内容类似:
module example.com/sps/crm go 1.27.0
这里的两个配置分别表示:
module:模块唯一标识
module example.com/sps/crm
模块路径通常也用于导入代码。
例如创建一个 service 包:
sps-crm/
├── go.mod
├── main.go
└── service/
└── customer.go
service/customer.go:
package service
func GetCustomerName() string {
return "SPS 客户"
}
main.go:
package main
import (
"fmt"
"example.com/sps/crm/service"
)
func main() {
fmt.Println(service.GetCustomerName())
}
运行:
go run .
输出:
SPS 客户
注意:
- module 是模块路径,不是本地文件夹名称。
- import 是包路径,通常由模块路径加包所在的相对目录组成。
- 不需要把模块放在 $GOPATH/src 目录下。
- example.com/sps/crm 是教学用的示例路径,实际项目推荐使用真实的 Git 仓库地址或可解析的私有模块路径。
go:最低 Go 版本要求
go 1.27.0
从 Go 1.21 开始,这不只是一个建议版本,而是实际的最低 Go 版本要求。
例如模块声明 Go 1.27,旧版本 Go 工具链不能直接按低版本规则构建它,Go 工具链还可能根据配置自动切换版本。
2. 完整的 go.mod 语法
下面是一个包含常见指令的示意文件。
module example.com/sps/crm
go 1.27.0
toolchain go1.27.3
require (
github.com/google/uuid v1.6.0
github.com/gin-gonic/gin v1.10.1
example.com/sps/common v0.1.0
)
// 本地开发时可临时启用
// replace example.com/sps/common => ../common
// 以下为其他指令的语法示例,
// 一般不会在同一个业务项目中全部使用:
// exclude example.com/legacy v1.2.0
// retract v0.1.0
// tool golang.org/x/tools/cmd/stringer
逐项解释:
| 指令 | 用途 | 是否常用 |
|---|---|---|
| module | 声明模块路径 | 必用 |
| go | 声明最低 Go 版本 | 必用 |
| require | 声明依赖模块及其版本 | 常用 |
| replace | 替换依赖模块来源 | 开发调试常用 |
| toolchain | 建议使用的 Go 工具链版本 | 视情况使用 |
| exclude | 排除某个依赖版本 | 较少 |
| retract | 标记自身模块的某些版本不应使用 | 模块发布时使用 |
| tool | 声明 Go 开发工具依赖,Go 1.24+ | 视情况使用 |
其中最需要掌握的是 require 和 replace。
3. require:管理项目依赖
例如 CRM 项目需要 UUID 库。
go get github.com/google/uuid@v1.6.0
随后 go.mod 会增加:
require github.com/google/uuid v1.6.0
代码里直接使用:
package main
import (
"fmt"
"github.com/google/uuid"
)
func main() {
id := uuid.New()
fmt.Println(id.String())
}
require 记录的是依赖模块路径及要求版本,不是直接引用某一个 .go 文件。
常用依赖管理命令:
# 安装或更新到指定版本 go get github.com/google/uuid@v1.6.0 # 获取最新版本 go get github.com/google/uuid@latest # 升级当前模块依赖 go get -u ./... # 移除某个依赖的要求 go get github.com/google/uuid@none # 整理依赖 go mod tidy
其中 go mod tidy 会根据代码及测试实际使用的包,补充缺失依赖并移除不再需要的依赖要求。
direct 和 indirect 的区别
你可能经常看到:
require (
github.com/google/uuid v1.6.0
golang.org/x/sys v0.30.0 // indirect
)
// indirect 表示间接依赖。
例如:

这只是一个依赖关系示例,并不是上面 UUID 库的真实依赖链。
不建议手工删除 // indirect 依赖,因为它们可能是模块图正确解析所必需的。
4. replace:替换模块来源
这是 Go 多模块开发中非常实用的功能。
假设:
projects/
├── crm/
│ └── go.mod
└── common/
└── go.mod
其中:
common/go.mod
module example.com/sps/common go 1.27.0
crm/go.mod
module example.com/sps/crm go 1.27.0 require example.com/sps/common v0.1.0 replace example.com/sps/common => ../common
这句的意思是:
replace example.com/sps/common => ../common
当 CRM 需要 example.com/sps/common 时,不去使用正常解析到的发布版本,而改为使用本地的 ../common 模块。
例如 CRM 代码:
import "example.com/sps/common/utils"
Go 就会在本地的 ../common/utils 中寻找代码。

replace 支持不同形式:
// 所有版本都使用本地目录 replace example.com/sps/common => ../common // 仅替换 v0.1.0 replace example.com/sps/common v0.1.0 => ../common // 使用另一个发布模块版本 replace example.com/sps/common v0.1.0 => example.com/fork/common v0.1.1
注意三个问题:
- 本地替换目录必须有自己的 go.mod。
- 单独写 replace 不等于添加依赖,依赖仍需进入模块图,通常通过 require。
- 如果把仅适用于自己电脑的 replace => ../common 提交到 Git,其他开发者或 CI 环境可能找不到这个相对路径。
因此,日常跨项目联调时往往更推荐使用 go.work。
5. go.sum:到底有什么用?
当项目使用外部依赖时,Go 通常会生成 go.sum。
例如:
sps-crm/ ├── go.mod ├── go.sum └── main.go
go.sum 中包含类似内容:
github.com/google/uuid v1.6.0 h1:... github.com/google/uuid v1.6.0/go.mod h1:...
其中 h1: 后面是真实的哈希校验值。
这里需要区分:
| 文件 | 作用 |
|---|---|
| go.mod | 记录模块的依赖要求及版本 |
| go.sum | 记录部分依赖模块内容和 go.mod 的校验哈希 |
go.sum 不是传统意义上的锁版本文件。
Go 使用 Minimal Version Selection(MVS,最小版本选择)算法,根据模块的依赖要求计算最终使用的版本。即使 go.sum 中保留多个版本的校验信息,也不代表构建时同时选择它们。
通常建议:
- go.mod 提交 Git。
- go.sum 提交 Git。
- 不要随意手动编辑或清空 go.sum。
- 依赖变化之后运行 go mod tidy。
三、go.work 详细讲解
go.work 的核心价值,是让多个独立的 go.mod 模块能够在本地共同开发。
1. 为什么需要 go.work?
假设 SPS 有三个系统:
SPS ├── CRM 客户关系系统 ├── OMS 订单管理系统 └── Common 公共模块
CRM、OMS 都依赖 Common:
CRM ──┐
├── Common
OMS ──┘
假设线上使用的 Common 版本为 v0.1.0。
现在你正在开发 Common 的新功能,例如:
func FormatAmount(amount float64) string {
// 新逻辑
}
希望 CRM 和 OMS 立即使用修改后的本地代码进行测试。
如果不使用 go.work,通常有两个选择:
- 发布一个新的 Common 版本,再修改 CRM、OMS 的依赖版本。
- 在 CRM、OMS 各自的 go.mod 中添加本地 replace。
但有了 go.work,只需要将三个模块加入工作区,就可以统一进行本地联调。
2. go.work 的文件结构
假设:
sps-workspace/
├── go.work
├── crm/
│ ├── go.mod
│ └── main.go
├── oms/
│ ├── go.mod
│ └── main.go
└── common/
├── go.mod
└── money/
└── money.go
工作区文件内容:
go 1.27.0
use (
./crm
./oms
./common
)
含义如下:
go 1.27.0
声明该工作区的最低 Go 工具链版本要求。
use ./crm
把当前目录下的 crm 模块加入工作区。
use ./oms
把 oms 模块加入工作区。
use ./common
把 common 模块加入工作区。
关键点:use 后面写的是本地模块目录路径,不是模块名称。每个引用的目录应当有自己的 go.mod。
在工作区模式下,Go 会把 use 指定的模块都作为主模块参与构建和依赖选择。
四、实战:从零搭建三个 Go 模块的工作区
下面用一个可以实际运行的例子演示。
目标:CRM、OMS 两个项目共同调用 Common 模块的金额格式化功能,并且修改 Common 后立即生效,不需要重新发布。
第一步:创建三个独立模块
mkdir sps-workspace cd sps-workspace mkdir -p common/money crm oms # 初始化 Common 模块 cd common go mod init example.com/sps/common # 初始化 CRM 模块 cd ../crm go mod init example.com/sps/crm # 初始化 OMS 模块 cd ../oms go mod init example.com/sps/oms cd ..
此时目录结构为:
sps-workspace/
├── common/
│ ├── go.mod
│ └── money/
├── crm/
│ └── go.mod
└── oms/
└── go.mod
第二步:编写 Common 公共模块
新建 common/money/money.go:
package money
import "fmt"
// Format 格式化金额
func Format(amount float64, currency string) string {
return fmt.Sprintf("%.2f %s", amount, currency)
}
这个模块可以被 CRM、OMS 复用。
第三步:CRM 引用 Common
新建 crm/main.go:
package main
import (
"fmt"
"example.com/sps/common/money"
)
func main() {
amount := money.Format(1280, "USD")
fmt.Println("CRM 客户报价:", amount)
}
将 Common 添加到 CRM 的依赖要求:
cd crm go mod edit -require=example.com/sps/common@v0.1.0 cd ..
CRM 的 go.mod:
module example.com/sps/crm go 1.27.0 require example.com/sps/common v0.1.0
这里 v0.1.0 是假设将来发布或已经发布的 Common 版本。使用 go mod edit 可以先写入依赖声明,不要求该版本此时已经存在于远程仓库。
第四步:OMS 也引用 Common
新建 oms/main.go:
package main
import (
"fmt"
"example.com/sps/common/money"
)
func main() {
amount := money.Format(950, "USD")
fmt.Println("OMS 订单成本:", amount)
}
同样添加依赖:
cd oms go mod edit -require=example.com/sps/common@v0.1.0 cd ..
第五步:创建 go.work 工作区
确保当前处于 sps-workspace 根目录。
执行:
go work init ./common ./crm ./oms
会自动生成:
sps-workspace/ ├── go.work ├── common/ ├── crm/ └── oms/
生成的 go.work 类似:
go 1.27.0
use (
./common
./crm
./oms
)
go 版本行会由当前实际使用的 Go 工具链决定,不一定与示例相同。
第六步:运行 CRM、OMS
在工作区根目录执行:
go run ./crm
输出:
CRM 客户报价: 1280.00 USD
再执行:
go run ./oms
输出:
OMS 订单成本: 950.00 USD
注意:即使 Common 的 v0.1.0 还没有发布,这两个项目仍然可以在工作区模式下找到本地 Common 代码。
第七步:验证本地修改是否立即生效
修改 common/money/money.go:
package money
import "fmt"
func Format(amount float64, currency string) string {
return fmt.Sprintf(
"金额:%.2f,币种:%s",
amount,
currency,
)
}
不需要发布 Common,也不需要修改 CRM 的版本号。
重新执行:
go run ./crm
输出:
CRM 客户报价: 金额:1280.00,币种:USD
这就证明 CRM 调用的是工作区里的 Common 本地源码。

注意,这里的“立即生效”指的是下一次编译或运行自动使用修改后的本地源码,并非运行中的进程自动热更新。
五、go.work 常用命令详解
1. go work init:创建工作区
go work init
创建空工作区。
或者:
go work init ./crm ./oms
创建工作区并添加两个模块。
2. go work use:增加模块
假设后来又开发了 FNS 财务系统。
sps-workspace/
├── go.work
├── crm/
├── oms/
├── common/
└── fns/
└── go.mod
只需要执行:
go work use ./fns
原来的 go.work 就会增加:
use (
./common
./crm
./oms
./fns
)
也可以递归发现某个目录下的 Go 模块:
go work use -r .
但需要注意,如果一个目录下还有大量不想加入工作区的测试模块、工具模块,就不建议无差别地递归加入。
3. go work edit:修改配置
例如添加一个模块:
go work edit -use=./fns
删除一个模块:
go work edit -dropuse=./fns
查看工作区配置的 JSON 形式:
go work edit -json
4. go work sync:同步依赖版本
这是容易误解的命令。
假设 CRM 和 OMS 都依赖同一个第三方模块:
CRM └── dependency A v1.2.0 OMS └── dependency A v1.5.0
工作区统一进行依赖选择时,根据 MVS 规则,在这个简化例子中会选择 v1.5.0。
执行:
go work sync
它会把工作区计算出的依赖版本同步到各模块相应的 go.mod 中。
示意:同步前后
| 模块 | 同步前 | 同步后 |
|---|---|---|
| CRM | A v1.2.0 | A v1.5.0 |
| OMS | A v1.5.0 | A v1.5.0 |
实际同步结果还取决于完整的依赖图。
这里必须注意:go work sync 可能修改多个模块的 go.mod 文件,并不是简单地刷新工作区。 因此建议执行前后都检查 Git Diff。
5. go env GOWORK:检查当前工作区
go env GOWORK
如果当前在工作区中,可能输出:
/Users/albert/projects/sps-workspace/go.work
说明当前使用了该工作区。
Go 会检查 GOWORK 环境变量,如果未指定,则从当前目录逐级向父目录寻找 go.work。
要临时禁用工作区:
GOWORK=off go run .
这个命令会忽略 go.work,按照单模块的依赖规则运行。
例如在 CRM 目录执行:
cd crm GOWORK=off go build .
此时就不再自动调用工作区里的本地 Common,而是按照 CRM 的 go.mod 去解析对应的发布版本。
如果 v0.1.0 尚未发布或不可访问,构建就可能失败。
六、go.mod、go.work、replace 三种模式如何选择?
用三个典型场景说明。
场景 A:只有一个业务系统
例如单独开发 CRM,项目内部有 handler、service、repository、model 等不同的包。
推荐:只使用一个 go.mod,不需要 go.work。
场景 B:CRM、OMS 和 Common 同时开发
多个模块都需要引用本地的 Common,开发人员经常跨模块修改代码。
推荐:每个模块独立 go.mod,本地用一个 go.work 联合管理。
场景 C:临时修改某一个第三方库
例如某个数据库驱动有问题,你下载源码准备调试它,但不打算把它加入长期工作区。
推荐:使用 replace 临时指向该库的本地目录。
七、实际开发最容易遇到的 6 个坑
坑 1:以为 go.work 可以代替 go.mod 的 require
例如:
// CRM 的 go.mod module example.com/sps/crm go 1.27.0
虽然 CRM 没有写 require common,但在工作区模式下,Go 仍可能解析到工作区里的 Common 并成功运行。
问题是,一旦退出工作区,CRM 就缺少正确的模块依赖声明。
建议:每个模块都应该维护自己完整、正确的 go.mod,不要依赖 go.work 掩盖缺失的依赖。
坑 2:使用 go.work 后,go mod tidy 仍然报错
这是特别值得注意的问题。
假设 Common 尚未发布:
require example.com/sps/common v0.1.0
即使已经通过 go.work 添加了 Common,本地执行:
cd crm go mod tidy
仍然可能尝试下载 example.com/sps/common v0.1.0 并报错。
原因是:go mod tidy 是针对单个主模块整理依赖的命令,不能理解成一定会使用工作区内所有本地模块代替远程依赖。
对于尚未发布的 Common,有几种处理方法:
- 等 Common 发布一个实际可用版本后,再运行 go mod tidy。
- 开发早期临时在 CRM 的 go.mod 中增加 replace,整理完后去掉临时替换。
- 在工作区模式下进行开发与联调,等发布流程准备好后再验证各模块的独立构建。
例如临时增加:
replace example.com/sps/common => ../common
整理:
go mod tidy
完成后移除临时替换:
go mod edit -dropreplace=example.com/sps/common
然后在依赖发布之后重新验证独立构建。
坑 3:在工作区根目录执行 go test ./...
假设:
sps-workspace/
├── go.work
├── crm/
│ └── go.mod
└── oms/
└── go.mod
你执行:
go test ./...
可能报:
pattern ./...: directory prefix . does not contain modules listed in go.work or their selected dependencies
这是因为工作区根目录本身并不一定是一个 Go 模块。
可以这样运行:
# 测试 CRM go test ./crm/... # 测试 OMS go test ./oms/... # 测试 Common go test ./common/...
或者进入对应模块目录:
cd crm go test ./...
坑 4:本地测试正常,CI/CD 却构建失败
开发者的电脑上:
CRM → 本地 Common 最新代码
但 CI/CD 环境可能只有:
CRM → go.mod 指定的 Common 发布版本
如果 CRM 使用了尚未发布的 Common 新接口,工作区中可能运行正常,但独立构建就会失败。
推荐在 CI 中增加独立模块验证:
cd crm GOWORK=off go mod tidy -diff GOWORK=off go test ./... GOWORK=off go build ./...
其中 go mod tidy -diff 用于检查依赖文件是否需要整理,不会直接改写文件。该参数需要相应版本的 Go 工具链支持。
前提是 CRM 所需的 Common 版本已经发布且 CI 可访问。
坑 5:把个人电脑路径提交到 Git
例如:
replace example.com/sps/common => /Users/albert/dev/common
这种写法可能在你电脑上正常,但在其他人的电脑或服务器上会失败。
不推荐把这种机器相关的绝对路径提交到共享代码库。
对于个人本地的多模块联调,可以把 go.work 放在工作区目录,并让它引用相对路径。
坑 6:不知道 go.work 是否应该提交 Git
官方文档一般不建议默认把 go.work 提交到版本控制,因为它可能改变其他开发者和 CI 的模块解析行为;但对于专门设计的多模块仓库,也有合理的提交场景。
可以采用这个原则:
| 场景 | 建议 |
|---|---|
| 个人开发者临时联合多个仓库 | 不提交 go.work |
| 多个独立仓库,各自构建发布 | 通常不提交 |
| 固定的 Monorepo,团队统一工作区 | 可以考虑提交 |
| CI/CD 独立验证模块发布版本 | 通常设置 GOWORK=off |
此外,工作区有时还会生成 go.work.sum,用来记录未被工作区内各模块 go.sum 覆盖的校验哈希。它不是取代各模块 go.sum 的文件。
八、go.mod 和 go.work 常用命令速查
| 命令 | 作用 |
|---|---|
| go mod init xxx | 创建模块 |
| go get xxx@v1.2.3 | 添加或调整指定版本依赖 |
| go mod tidy | 整理当前模块依赖 |
| go mod download | 下载模块依赖 |
| go mod verify | 验证已下载依赖 |
| go list -m all | 查看参与构建的模块版本列表 |
| go mod graph | 查看依赖图 |
| go mod why -m xxx | 分析模块依赖原因 |
| go mod edit -replace=... | 修改依赖替换规则 |
| go work init | 创建工作区 |
| go work use ./xxx | 添加或更新工作区模块 |
| go work use -r . | 递归发现模块 |
| go work edit -json | 查看工作区 JSON 配置 |
| go work sync | 同步工作区依赖版本到模块 |
| go env GOWORK | 查看当前工作区文件 |
| GOWORK=off go test ./... | 不使用工作区进行测试 |
九、针对实际业务系统的工程建议
假如后续准备开发多个 Go 业务系统,我建议优先采用下面这种结构。
sps-projects/
│
├── go.work # 本地联合开发
│
├── sps-common/ # 公共基础模块
│ ├── go.mod
│ ├── logger/
│ ├── errors/
│ └── utils/
│
├── sps-crm/ # CRM 系统
│ ├── go.mod
│ ├── cmd/
│ ├── internal/
│ └── api/
│
├── sps-oms/ # OMS 系统
│ ├── go.mod
│ ├── cmd/
│ ├── internal/
│ └── api/
│
└── sps-fns/ # 财务系统
├── go.mod
├── cmd/
├── internal/
└── api/
对应的开发与发布规则:
- 模块边界清晰:CRM、OMS、FNS 各自负责自己的业务,公共模块只存放真正需要共享的基础能力。
- 版本独立管理:Common 单独发布版本,业务模块通过 require 引用明确版本。
- 本地使用 go.work:联合开发期间直接使用 Common 最新源码。
- CI 独立验证:每个业务模块在 GOWORK=off 模式下也必须能够构建、测试。
- 避免过度拆模块:不需要把 CRM 的 handler、service、repository 都拆成独立 Go Module,它们通常只需要作为同一个模块下的 Package。
最终怎么选择?
优先单模块,真正需要独立版本和跨项目复用时再拆成多模块。
一个业务系统内部有几十个 Package 完全正常,并不意味着需要几十个 go.mod。go.work 解决的是多模块本地协作,不是模块拆分的理由。
官方参考资料:Go Modules Reference · Go Workspace Tutorial · Managing Dependencies