单体go工程切多模块易失败，因go工具链严格校验模块路径与导入路径一致性；必须确保go mod init路径等于实际import路径，replace仅限本地调试且需所有依赖模块同步配置，稳定方案是子模块推远程打tag后require引用。
单体 Go 工程直接 go mod init 后切多模块，大概率会失败——不是因为语法不支持，而是 go 工具链对模块路径、导入路径、replace 和 require 的一致性校验非常严格，稍有不匹配就报 module declares its path as ... but was downloaded as ...。
模块路径必须与实际导入路径完全一致
Go 不允许“声明路径”和“被引用路径”错位。比如你把 internal/pkg/auth 提成独立模块，模块名设为 github.com/org/auth，但老代码仍用 import "myproject/internal/pkg/auth"，就会触发校验失败。
- 迁移前先全局搜索所有
import语句，确认目标包的当前导入路径 - 新建模块时，
go mod init的参数必须是将来被其他模块 import 时使用的完整路径（如go mod init github.com/org/auth） - 模块根目录必须能通过该路径被
go get或本地replace正确解析，不能放在cmd/或internal/下——Go 模块根必须是仓库根或明确子路径
本地 replace 不是万能补丁，它会掩盖路径不一致问题
replace 能临时指向本地路径，但只在当前主模块生效；一旦其他模块也依赖该子模块，而它们没配 replace，就会去拉远程版本——如果远程还没发布，或版本不匹配，立刻失败。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 开发阶段可用
replace github.com/org/auth => ../auth，但必须确保所有依赖它的模块都加相同replace（否则 CI 构建必然失败） - 真正稳定的方案是：子模块推送到真实远程地址，并打 tag（如
v0.1.0），主模块用require github.com/org/auth v0.1.0 -
replace路径必须是绝对路径或相对于主模块go.mod的相对路径，不能用./auth这种模糊写法——Go 会报invalid replace directive
go.work 是多模块协作的起点，不是替代 go.mod
go.work 文件只用于本地开发时聚合多个模块，它本身不参与构建、不上传到仓库、也不影响 go build 的默认行为。误以为加了 go.work 就不用管各模块的 go.mod，是常见误区。
- 每个子模块仍需独立的
go.mod，且必须包含module声明和正确的require列表 -
go work use ./auth ./api生成的go.work只告诉go命令：“这些目录里的模块我一起管”，但不会自动同步版本或修复导入路径 - CI 环境通常不读
go.work，所以线上构建仍依赖各模块自身的go.mod是否自洽
最常被忽略的一点：Go 模块路径不是“起个名字就行”，它是导入系统的唯一标识符。改路径 ≠ 改文件夹名，它牵动所有 import、CI 配置、文档链接甚至 IDE 缓存。动手前，先跑通 go list -m all 和 go mod graph | grep 看依赖拓扑，比直接删 go.mod 安全得多。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
