在Go语言项目逐渐膨胀之后，单一模块往往难以支撑复杂的业务边界，不少团队会把代码拆成多个go.mod管理的模块。此时依赖该如何统一管理，才能保证本地开发顺畅、持续集成可复现、跨团队协作不混乱，是实际工程中必须面对的问题。下面汇总几种主流做法并分析其适用场景。
使用Go Workspaces进行多模块本地协同
Go 1.18引入了工作区（workspace）模式，通过根目录下的go.work文件把多个本地模块聚合在一起。在工作区中，所有被纳入的模块会优先使用本地源码，而不去下载远程版本，这极大简化了多模块并行开发。
创建方式非常简单，在几个模块的共同父目录执行命令即可生成go.work，其中use指令列出各模块路径。构建时Go工具链会自动以工作区为准，忽略各模块go.mod里对彼此的版本约束。这种方式不需要修改任何模块的go.mod，对CI也友好，因为CI若不启用工作区就会回退到正常版本拉取。
// 目录结构：
// demo/
// go.work
// user/
// go.mod
// order/
// go.mod
// go.work 内容示例
go 1.21
use (
./user
./order
)
// 在 order 模块中直接 import user 模块，无需发布版本
// order/main.go
package main
import (
"fmt"
"user/service"
)
func main() {
fmt.Println(service.GetName())
}
工作区模式的优点是零侵入、切换方便，缺点是仅限本地或特定环境使用，不能替代正式的版本发布。若团队成员忘记启动工作区，就可能误装旧版本，因此一般配合文档或Makefile使用。
利用replace指令指向本地或特定源
在单个模块的go.mod中，replace可以改变某个依赖的获取路径与版本。最常见的用法是把公司内部模块指向本地磁盘目录，便于未发版前联调。
例如user模块还在开发中，order模块可以直接replace到本地绝对或相对路径。注意replace只在当前模块构建时生效，且不会传递给依赖当前模块的其他模块，这一点和workspace不同。下面的示例展示了如何在order模块的go.mod里替换user源。
// order/go.mod module order go 1.21 require user v0.0.0 replace user => ../user // 构建时 Go 会读取 ../user 下的源码而非代理仓库
replace虽然灵活，但容易在提交时遗漏而导致CI失败，所以通常建议把replace段落写在单独的开发用go.mod分支，或借助工作区替代。它更适合临时修补第三方依赖，比如将存在bug的上游库指向自己fork的仓库。
发布独立模块并依靠语义化版本
当模块需要被多个团队或外部项目复用时，最稳妥的方案是把每个模块作为独立仓库，通过tag发布语义化版本（如v1.2.0）。其他模块在go.mod中以require声明具体版本，由Go module proxy统一分发。
这种方式的优势在于依赖关系清晰、可回溯、CI完全可复现，且不受本地环境影响。代价是每次改动都要走发版流程，开发反馈链路较长。为了缓解这个问题，可搭配轻量工作区做本地验证，发版前移除replace与工作区配置。
// 发布 user 模块 // 在 user 仓库执行 git tag v1.0.0 git push origin v1.0.0 // order/go.mod 中直接引用发版地址 module order go 1.21 require user v1.0.0
采用正式发版后，go.sum会锁定校验值，安全性更高。对于大型组织，还可以搭建私有proxy缓存常用模块，进一步提速构建。
不同方案对比与选型建议
为了直观理解三种方式的差异，可以从侵入性、协作范围和适用阶段三个维度比较。
| 方案 | 配置位置 | 是否侵入go.mod | 适合场景 |
|---|---|---|---|
| Go Workspaces | go.work | 否 | 本地多模块并行开发 |
| replace指令 | 各模块go.mod | 是 | 临时联调、fork修补 |
| 语义化发版 | 远程仓库tag | 否（仅require） | 跨团队、生产交付 |
实践中往往是组合使用：日常开发开工作区，临时修补用replace，稳定接口走发版。只要理清require与replace的优先级，以及工作区对replace的覆盖规则，多模块依赖就不会成为Go工程的绊脚石。
常见误区与排查思路
一个典型误区是认为在go.work里use某个模块后，该模块go.mod中的replace也会全局生效。实际上工作区主要覆盖版本选择，模块自身的replace仍按原逻辑执行，只是最终版本会被工作区路径接管。
遇到依赖拉取异常时，可依次执行go work sync、go mod tidy以及go list -m all查看解析结果。若CI报找不到模块，先确认是否误提交了replace或缺少tag。理清这些机制，多模块管理就能做到既灵活又稳健。