答案是因replace仅映射路径而不同步依赖树，本地模块的module名不匹配或其内部依赖未被主项目显式接受，导致go mod tidy发现版本解析与go.mod记录不一致。
为什么 go mod tidy 会报错 “require …: version … used for … but not listed in go.mod”
这是本地开发时最常遇到的依赖冲突信号——你用 replace 指向了本地模块，但该模块的 go.mod 里声明的 module 名与主项目引用的路径不一致，或者本地模块自己依赖了其他版本的包，而这些版本未被主项目显式接受。
典型表现是：本地改完代码后运行 go run 或 go build 失败，错误里夹着类似 require github.com/xxx/lib v1.2.3: version v1.2.3 used for github.com/xxx/lib but not listed in go.mod 的提示。
- 根本原因不是版本号“冲突”，而是 Go 模块系统发现某依赖的实际解析版本和
go.mod中记录的不一致，且无法自动补全 -
replace只影响路径映射，不自动同步依赖树；被替换模块内部的require仍需在主项目中可解析 - 如果本地模块用了
indirect依赖（比如通过 transitive 引入），而主项目没显式 require 它，go mod tidy就会拒绝收敛
如何正确使用 replace + upgrade 组合修复本地开发链路
单纯写 replace github.com/xxx/lib => ./local-lib 往往不够。你需要让主项目的依赖图真正“认出”本地模块所依赖的全部版本。
执行顺序很关键：先让本地模块自洽，再让它被主项目接纳。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 进入本地模块目录，运行
go mod tidy，确保它的go.mod完整、无indirect遗留 - 回到主项目根目录，删掉
go.sum（可选，但能避免校验残留干扰） - 执行
go mod edit -replace github.com/xxx/lib=./local-lib（比手动编辑更安全） - 再跑一次
go mod tidy—— 这次它会把本地模块的全部require向上合并到主项目的go.mod中 - 如果仍有报错，检查本地模块的
go.mod第一行module是否和主项目replace的路径完全一致（包括大小写、斜杠方向）
当本地模块尚未打 tag 时，go.mod 中的 pseudo-version 是怎么生成的
Go 不允许 replace 后还用 v0.0.0-00010101000000-000000000000 这类无效时间戳。它会在 go mod tidy 时根据本地模块的 git commit 自动生成 pseudo-version，格式为 v0.0.0-{YYYYMMDDHHMMSS}-{commit-hash}。
这个值会被写进主项目的 go.mod 和 go.sum，用于校验一致性。一旦你本地 git commit 变了，pseudo-version 就变，go mod tidy 就可能再次触发更新。
- 不要手动修改
go.mod里的 pseudo-version —— 它是只读结果，不是配置项 - 如果本地模块没 git repo（比如只是文件夹），Go 会拒绝生成 pseudo-version，报错
no module path，此时必须先git init && git add . && git commit -m "init" - 伪版本中的时间戳来自最近一次 commit 的 author time，不是本地系统时间，所以多人协作时要注意 git 提交时间是否可信
多级 replace 场景下为何 go list -m all 会暴露隐藏依赖问题
当你在 A 项目中 replace B，而 B 本身又 replace C，Go 默认不会递归解析 C。这时 go list -m all 能帮你看到实际加载的模块全貌，比 go mod graph 更直接。
运行它，你会看到所有模块及其最终解析路径。如果某行显示 github.com/xxx/c v0.1.0 => /path/to/c，说明 C 已被正确替换；但如果仍是 github.com/xxx/c v0.1.0（无 =>），说明 B 里的 replace 没被主项目继承 —— Go 不跨模块继承 replace。
- 解决方案只有两个：要么在主项目里也显式
replaceC；要么把 B 的replace提升到主项目层级 -
go list -m all | grep c是快速验证是否生效的命令 - 注意
go list -m all -f '{{.Replace}}'可以只输出替换路径，适合脚本化检查
replace 的作用域就越窄。别指望一个 replace 解决所有嵌套问题，每个需要覆盖的模块都得在顶层显式声明。 
