replace需严格匹配模块路径与本地路径，左边为import路径、右边为相对于go.mod的绝对或相对路径；go.work中use仅支持目录且不可重叠；go list -m all须加-work才反映完整工作区视图。
Go mod replace 怎么写才不踩坑
直接用 replace 覆盖本地模块路径时，最常见问题是 Go 工具链找不到依赖或构建失败——根本原因往往是路径没对齐、版本号冲突，或 go.mod 里没同步更新依赖树。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
replace的左边必须是模块路径（即import语句里写的那个），右边是本地绝对路径或相对路径；相对路径以go.mod所在目录为基准，不是执行命令的目录 - 如果被替换的模块本身有
replace或require，它不会自动继承；主模块需显式require对应版本，否则go build可能静默忽略 - CI 环境下禁止用相对路径
replace；统一改用file://绝对路径，或通过GOEXPERIMENT=aliases+go mod edit -replace动态注入 - 示例：项目根目录
go.mod中写replace example.com/lib => ./internal/lib，前提是internal/lib/go.mod里module声明必须是example.com/lib，不能是./internal/lib或空字符串
多 module 共存时 go.work 怎么组织
go.work 不是“替代 go.mod”，而是让多个独立 go.mod 在同一工作区里共享依赖解析上下文；误以为它能绕过模块边界，就会遇到 cannot load 或 ambiguous import 错误。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 每个子模块必须自带合法
go.mod（含正确module名和go版本），go.work只负责把它们“拉进同一个视图” -
use指令只接受目录路径，不支持通配符；子模块目录名不必和模块名一致，但路径不能重叠（比如use ./a和use ./a/b会冲突） - 运行
go run或go test时，当前工作目录若在某个子模块内，且该模块不在go.work的use列表中，Go 会退回到单模块模式，导致本地修改不生效 - 示例：
go.work内容为use ( ./cmd/api ./pkg/storage ./internal/tools )，则所有跨模块 import（如import "example.com/pkg/storage"）才能被正确解析
vendor 目录在 Monorepo 里要不要开
开 vendor 会锁死依赖版本，但也让构建更确定；但在 Monorepo 场景下，它容易变成“假隔离”——不同子模块 vendor 同一依赖的不同 commit，反而引发运行时行为不一致。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 全项目统一关掉
vendor（即不执行go mod vendor），靠go.work+go.sum保证一致性；这是大多数 Go Monorepo 的实际选择 - 只有当某子模块要发布为独立二进制（如 CLI 工具），且需离线构建时，才在该模块下单独启用
vendor，并用go mod vendor -o ./vendor显式指定输出位置，避免污染其他模块 - CI 中禁用
GOFLAGS=-mod=vendor；它会让整个工作区强制走 vendor，绕过go.work的模块映射逻辑，导致本地开发和 CI 行为割裂
go list -m all 为什么在 work 模式下结果不对
执行 go list -m all 时，默认只读取当前目录的 go.mod，完全无视 go.work；想看整个工作区的模块视图，必须加 -work 标志，否则列出的只是“局部快照”，不是真实依赖图。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 查依赖关系用
go list -m -work all，查某个模块的依赖树用go list -deps -f '{{.Path}}' -work ./cmd/api -
go list -m -u all（检查更新）在 work 模式下无效，它只对单个go.mod生效；批量升级需逐个进入子模块目录执行 - IDE（如 VS Code + Go extension）是否识别
go.work，取决于go.goroot和go.toolsEnvVars配置；若提示 “no modules found”，先确认go version≥ 1.18 且当前文件夹存在有效的go.work
Monorepo 的复杂性不在结构本身，而在模块边界与工具链默认行为的错位；很多问题其实就卡在一行 replace 路径少了个点，或者忘了加 -work 标志。
