go mod replace 是临时重定向模块路径，仅在当前 module 生效；用于本地调试、fork 修复、私有模块替代等场景，需确保路径、go.mod 和 module 名三者完全一致。
go mod replace 不是“排除”，而是“替换”
很多人想“排斥”某个模块，其实是希望构建时不走远程拉取、不使用官方版本，或者干脆跳过它。Go 没有 exclude 语法来直接删掉一个依赖，replace 是唯一能干预依赖来源的机制——但它本质是映射，不是屏蔽。
常见错误是写：replace github.com/bad/pkg => /dev/null 或空路径，这会导致 go build 报错 cannot find module providing package，因为 Go 仍会尝试读取该路径下的 go.mod。
- 真正有效的“排斥”方式，是让
replace指向一个**合法但不含该包的最小模块**（比如空go.mod目录） - 更稳妥的做法是：先确认该模块是否真被 import —— 如果代码里根本没
import它，go mod tidy会自动删掉它，根本不需要replace - 如果它只是间接依赖（
// indirect），且你确定上游已修复兼容性问题，可先go get升级主依赖，再运行go mod tidy，让它自然脱落
用空模块目录实现“逻辑排斥”
当你必须让构建系统忽略某个模块（例如因许可证冲突、构建失败或调试需要），可行做法是创建一个只含 go.mod 的空目录，并用 replace 指向它：
mkdir -p ./stub/github.com/bad/pkg echo "module github.com/bad/pkg" > ./stub/github.com/bad/pkg/go.mod
然后在项目 go.mod 中添加：
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
replace github.com/bad/pkg => ./stub/github.com/bad/pkg
这样 Go 会解析到这个空模块，但只要你的代码没实际 import 它的任何包，就不会报错；一旦某处 import 了 github.com/bad/pkg/somefunc，构建就会失败——这反而是你想要的“暴露问题”效果。
- 该方法仅适用于你**完全控制代码引用行为**的场景，不能用于已有 import 且需运行时功能的情况
- 注意路径必须是相对路径（
./stub/...），绝对路径在 CI 或他人机器上会失效 -
go mod tidy会保留这条replace，但不会把它当真实依赖计入go list -m all
排查“看似未用却删不掉”的模块
运行 go mod tidy 后，某些模块仍留在 go.mod 里，你以为它没被用，其实可能藏在这些地方：
- 测试文件（
*_test.go）里 import 了它，而你没运行go test就直接tidy—— 默认会扫描测试文件，但若GOOS不匹配或用了//go:build !test，就可能漏掉 -
//go:embed或//go:generate注释里写了包路径，例如//go:generate go run github.com/xxx/tool，tidy不识别这种引用 - 构建标签（
// +build linux）限制的文件，在当前环境未启用，里面的import就不会被扫描到 - 空导入（
import _ "github.com/bad/pkg"）会被tidy当作显式依赖保留，哪怕没调用任何符号
验证是否真被引用：执行 go list -f '{{.Imports}} {{.Deps}}' ./... | grep bad/pkg，看输出中是否有匹配项。
离线编译时彻底绕过网络依赖
如果你的目标是“本地编译且不触网”，关键不是排斥某个模块，而是确保整个依赖图都可离线解析：
- 先在联网环境跑
go mod download，把所有依赖拉到本地缓存（$GOPATH/pkg/mod） - 用
go mod edit -replace把所有远程模块映射到缓存中的具体路径，例如：go mod edit -replace golang.org/x/net=~/go/pkg/mod/golang.org/x/net@v0.25.0 - 编译时加
-mod=readonly，防止意外触发go get - 如需打包分发，再配合
go mod vendor，但注意：vendor 不会自动清理旧文件，建议先rm -rf vendor再执行
真正容易被忽略的是：即使所有 replace 都指向本地路径，只要 go.mod 里还留着原始 require 行，go build 在 -mod=readonly 下仍会校验 go.sum —— 所以务必同步运行 go mod tidy，它会更新 go.sum 并剔除未被 replace 覆盖的校验项。
