模块边界由go.mod文件位置、require声明和GOPRIVATE配置共同决定，Go只认当前构建目录向上最近的go.mod，路径与go.mod组合定义边界，非目录结构本身。
多个 go.mod 共存时，模块边界由什么决定
Go 不会自动扫描整个仓库找 go.mod，它只认当前构建命令执行目录向上最近的那个 go.mod。也就是说，go build ./ 在 service/user/ 目录下运行，就只加载 service/user/go.mod 及其依赖；在根目录运行，则只认根 go.mod（如果存在）。模块边界本质是路径 + go.mod 的组合，不是目录结构本身。
常见错误现象：cannot load github.com/yourorg/lib: module github.com/yourorg/lib is not a dependency of module github.com/yourorg/app——这说明你正在用主模块的构建上下文去 import 一个未声明为依赖的本地子模块。
- 每个独立
go.mod必须有唯一、可解析的模块路径（如github.com/yourorg/pkg/auth），不能重复或模糊 - 子模块之间不能直接 import 彼此的 internal 包；
internal/对模块外完全不可见，哪怕物理路径相邻 - 跨模块调用必须走
pkg/或顶层公开包，且该包需在被 import 方的go.mod中通过require声明
replace 指令只对当前模块生效，别误以为它是全局开关
replace 是开发阶段的“本地映射”，仅影响写它的那个 go.mod 文件所定义的模块。它不会让其他模块也自动指向本地路径，也不会改变远程模块路径的语义。
典型误用：在根 go.mod 里写 replace github.com/yourorg/lib => ./lib，然后期望 cmd/app/go.mod 也能免配置引用 ./lib——不行。每个模块要自己声明 replace，或统一通过 require + 版本号管理。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- CI 构建前务必检查所有
go.mod是否含replace；可用grep -r "replace " . --include="go.mod" - 发布前删
replace不够，还要跑go mod tidy确保远程依赖能正常 resolve，否则go build会卡在 download 阶段 - 若多个模块共用同一套本地库，建议抽成独立 repo 并打 tag，比满仓
replace更可控
go.sum 不同步 = 构建不可重现
每个模块的 go.sum 是独立校验文件，记录该模块直接和间接依赖的 checksum。把所有 go.sum 合并、或删掉子模块的 go.sum，会导致 go mod verify 失败或静默跳过校验。
错误现象：verifying github.com/some/lib@v1.2.3: checksum mismatch，但本地 go mod tidy 没报错——大概率是某个子模块没更新自己的 go.sum，而主模块用了旧快照。
- CI 流水线中，对每个含
go.mod的目录执行go mod tidy && go mod verify - 不要
git add -f忽略子模块的go.sum；它们和go.mod一样是必需品 - 使用
go list -m -f '{{.Dir}} {{.Version}}' all可快速对比各模块实际加载版本是否一致
私有模块路径必须配 GOPRIVATE，否则 replace 也救不了
即使写了 replace git.company.com/internal/auth => ./internal/auth，如果没设 GOPRIVATE=git.company.com/*，go mod download 还是会尝试走 proxy（比如 proxy.golang.org），然后 404 或 timeout，最终构建失败。
这不是 replace 失效，而是 Go 在解析模块路径时，先判断是否私有——没配 GOPRIVATE，就默认走公共 proxy 流程，根本不会走到本地路径映射那步。
-
GOPRIVATE必须在go命令执行环境里生效，CI 脚本中要显式export GOPRIVATE=... - 通配符支持
*和**，但推荐用精确前缀，比如GOPRIVATE=git.company.com/internal,git.company.com/libs - 配完后验证：运行
go env GOPRIVATE，确认输出非空；再试go mod download git.company.com/internal/auth是否不再报 proxy 错误
go.mod 文件位置、require 声明、GOPRIVATE 配置三者共同硬性约束的结果。任何想绕过这些机制做“软耦合”的尝试，都会在 CI 或换机器时暴露。 
