replace语句必须写在主模块的go.mod文件中，仅对当前模块生效，不可在私有包自身go.mod中定义；路径需含有效go.mod且可读，需手动go mod tidy更新依赖和go.sum。
replace 语句必须写在主模块的 go.mod 文件里
Go 的 replace 只对当前模块（即包含 go.mod 的目录）生效，不能在私有包自己的 go.mod 里写 replace 来影响下游调用方。常见错误是把 replace 放错位置，导致调试时根本没生效。
正确做法：在你正在开发的应用（主模块）的 go.mod 中添加：
replace github.com/your-org/private-lib => ./local/private-lib
或指向本地 Git 仓库路径（支持绝对/相对路径），只要该路径下存在有效的 go.mod 即可。
- 路径必须可读，且含
go.mod；否则go build会报no matching versions for query "latest" - 如果私有包本身依赖其他模块，这些依赖仍按原
go.mod解析，replace不递归生效 - 使用
go list -m all | grep private-lib可确认是否已替换成功（输出中应显示=> ./local/private-lib）
replace 后要重新触发依赖解析
replace 不会自动触发 go mod tidy 或更新 go.sum，很多开发者改完 go.mod 就直接 go run，结果还是旧代码。
必须手动执行：
go mod tidy
这一步会：重新计算依赖图、更新 go.sum、清理未使用项，并确保本地路径被真正纳入构建流程。
- 若遇到
checksum mismatch，说明go.sum里还存着旧版本的校验和，go mod tidy会自动修正 - 编辑本地私有包后，无需重复
go mod tidy，只要源码变更能被 Go 工具链识别（如保存文件、修改.go内容），go build就会加载最新代码 - CI/CD 环境中禁用
replace—— 它只适用于本地开发，提交前应删掉或注释掉replace行
用 replace 调试时，go get 会绕过私有仓库配置
如果你通过 go get github.com/your-org/private-lib@v1.2.3 安装过私有包，Go 默认会尝试走 GOPROXY（比如 https://proxy.golang.org），而它无法访问你的私有仓库，就会失败。
但加上 replace 后，go get 实际不再拉取远程版本，而是直接链接本地路径 —— 所以此时 GOPROXY 和 git config 都不生效。
- 这意味着：即使你没配
~/.netrc或git config --global url."ssh://git@github.com/".insteadOf "https://github.com/"，replace也能工作 - 反过来说：如果
replace没生效，却看到403 Forbidden或authentication required错误，基本可以断定replace根本没被读到（检查路径拼写、go.mod 位置、模块名大小写） - 私有包模块名必须与
replace左侧完全一致（包括大小写），Go 不做模糊匹配
replace 不等于 vend
replace 是构建时重定向，不是复制源码。它不会把私有包内容塞进 vendor/，也不会改变 go install 的行为逻辑。
例如：
go install ./cmd/myapp
只要 myapp 的 go.mod 里有 replace，安装生成的二进制就已包含本地私有包的最新逻辑。
- 但如果你用
go install github.com/your-org/private-lib@latest，这个命令完全无视主模块的replace，它只认自己所在模块的go.mod -
replace对go test同样有效，测试运行时加载的就是本地路径下的代码 - 多级嵌套依赖中，只有最顶层模块的
go.mod中的replace生效；子模块里的replace被忽略
真正容易被忽略的是：replace 的路径一旦写成相对路径（比如 ./private），移动主模块目录后就会失效；还有人误以为 replace 后能用 go mod graph 看到“本地路径节点”，其实它只显示模块名，不显示映射目标 —— 得靠 go list -m -f '{{.Replace}}' 查。
