replace必须写在go.mod末尾、require块之后且独立成块；本地路径替换需满足相对路径、匹配module声明、存在有效go.mod三条件；远程replace必须带版本号；缓存需手动清理。
replace 必须写在 go.mod 末尾，且不能嵌套在 require 块里
Go 工具链只认 replace 出现在 require 块之后、exclude 或 retract 之前的位置。如果把它写进 require 里面（比如缩进对齐或夹在中间），Go 会直接忽略——不报错、不警告，静默失效。
常见错误写法：require ( github.com/sirupsen/logrus v1.9.3 replace github.com/sirupsen/logrus => ./local/logrus)
这整段会被当作非法语法跳过。
- 正确位置：所有
replace行必须紧接在)结束符之后，单独成块 - 顺序无关，但建议按字母序排列，方便人工核对
- 多个
replace可并存，彼此不干扰
本地路径替换必须满足三个硬性条件
哪怕 replace 语法和位置都对，只要漏掉下面任一条件，Go 就会退回到远程下载，你改的代码根本不会被编译进去。
-
./local/path必须是相对于当前go.mod所在目录的相对路径（不能用../跨父级，除非目标模块根目录确实匹配） - 该路径下必须存在有效的
go.mod文件，且第一行module声明与replace左侧路径**完全一致**（包括大小写、末尾斜杠、版本后缀） - 目标模块至少有一个
require或导出符号（空go.mod+ 空main.go可能被跳过）
验证是否生效，别信 IDE 高亮，运行：go list -m all | grep your-module-name
输出带 => ./local/path 才算真正命中。
replace 指向远程模块时必须带版本号
写成 replace github.com/a/b => github.com/c/b 是无效的——Go 不允许纯路径映射，必须指定版本，否则解析失败。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 正确写法：
replace github.com/a/b => github.com/c/b v1.2.3 - 支持
v1.2.3、master（仅限 Git 仓库）、latest（不推荐，行为不稳定） - 不能省略版本；也不能写成
=> github.com/c/b v0.0.0-00010101000000-000000000000这类伪版本，除非你明确生成过 - 这种写法仍会触发远程下载，只是换源；而
./local/path才真正绕过网络
go mod tidy 后缓存不更新？先清掉再重试
go mod tidy 不会自动刷新已缓存的模块元数据。如果你改了 replace 但 go build 还在拉远端，大概率是旧缓存没清理干净。
- 执行
go clean -modcache彻底清空本地模块缓存（路径通常是$GOPATH/pkg/mod） - 再跑一次
go mod tidy，让 Go 重新解析依赖图 - CI/CD 中建议加
GOFLAGS="-mod=readonly"，提前暴露未清理的 replace 遗留问题 - 注意：
go mod download对replace到本地路径的模块完全无视——它只管远程模块
最麻烦的其实是 module 名一致性：大小写、拼写、v2+ 路径后缀（如 /v2）差一个字符，replace 就彻底失效，而且没有任何提示。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
