go.mod 文件格式错位、replace 与 exclude 混用、indirect 标记误删/误加、go111module=off 环境下误改，均会导致构建失败或依赖异常；应优先使用 go mod tidy、go fmt -mod=mod 等工具自动修正，避免手动编辑。
go.mod 文件格式错位：require 行末多空格或换行丢失
Go 模块文件对空白符极其敏感，require 后面的模块路径和版本号必须在同一行，且不能有多余空格分隔（尤其不能用多个空格代替 tab）。常见现象是手动编辑后出现 go: malformed module path "xxx": invalid char "@" 或 go: errors parsing go.mod。
- 正确写法：
require github.com/sirupsen/logrus v1.9.3（单空格分隔，无换行、无 trailing 空格） - 错误写法：
require github.com/sirupsen/logrus v1.9.3（两个空格）、require github.com/sirupsen/logrusnv1.9.3（换行）、require github.com/sirupsen/logrus v1.9.3（末尾空格） - 修复建议：用
go fmt -mod=mod自动重排（它会清理空格但不改语义），或直接删掉整行再用go get重加
replace 和 exclude 混用导致 go build 失败
replace 是开发期临时覆盖依赖路径，exclude 是彻底剔除某版本——二者逻辑冲突，Go 1.17+ 会静默忽略 exclude 并优先走 replace，但构建时可能因版本不一致触发 missing go.sum entry 或 version mismatch 错误。
- 典型场景：本地调试时加了
replace github.com/foo/bar => ./bar，又写了exclude github.com/foo/bar v1.2.0 - 真实影响：go.sum 里仍会记录被 replace 的原始模块哈希，但构建时实际加载的是本地路径，校验失败
- 实操建议：开发中只用
replace；如需剔除某个有漏洞的旧版本，应删掉exclude，改用go get github.com/foo/bar@v1.3.0升级并更新 require 行
go.mod 中 indirect 标记被误删或误加
indirect 不是注释，是 Go 工具链标记间接依赖的关键标识。手动删掉它不会报错，但下次 go mod tidy 可能重新拉取旧版，或把本该直接依赖的包降级为间接依赖，引发 undefined identifier 或 cannot find package。
- 何时该有
indirect：该模块未在代码中直接 import，仅因其他依赖引入（比如github.com/gorilla/mux依赖go.opentelemetry.io/otel，而你没直接用 otel） - 何时不该有：你在
main.go里写了import "golang.org/x/sync/errgroup"，那它在require行就不能带indirect - 修复动作：运行
go mod graph | grep your-module查依赖来源；确认后执行go mod tidy自动修正，别手改indirect
GO111MODULE=off 环境下误改 go.mod 导致模块失效
当环境变量 GO111MODULE 被设为 off，Go 工具链会完全忽略 go.mod 文件，所有操作退化为 GOPATH 模式。此时手动改了 go.mod，看起来“保存成功”，但 go build 仍按老路径找包，go list -m all 也看不到任何模块信息。
立即学习“go语言免费学习笔记（深入）”；
- 快速判断：执行
go env GO111MODULE，输出不是on就是隐患 - 常见诱因：IDE 启动脚本、CI 配置、或某次调试临时 export 过该变量且没恢复
- 解决方式：在项目根目录下执行
export GO111MODULE=on（linux/macos）或set GO111MODULE=on（windows cmd），再运行go mod download验证是否生效
手动改 go.mod 最危险的不是语法错，而是改完没触发 go mod tidy 或没验证 go list -m all 输出——工具链不会主动告诉你哪一行“看起来对但实际被跳过”。