go111module=on 必须设置在项目含 go.mod、位于 $gopath 外、依赖私有仓库或需锁定 go.sum 时；auto 易误判，off 彻底退化为 gopath 模式，仅限极少数遗留场景。
GO111MODULE=on 什么时候必须设
Go 1.11 引入 Modules 后，GO111MODULE 决定是否启用模块感知模式。不是“推荐开启”，而是“不设就可能出错”——尤其当你在 $GOPATH 外写代码、依赖非标准仓库（如私有 Git）、或需要锁定 go.sum 时。GO111MODULE=auto 看似省事，但它只在当前目录外有 go.mod 或不在 $GOPATH 时才启用模块，容易误判。
常见错误现象：go build 报 cannot find module providing package xxx，但明明 go.mod 里写了依赖；或者 go get 拉的是 master 最新版而非 go.mod 锁定的版本。
-
GO111MODULE=on是最安全的默认值，强制所有操作走模块逻辑，无视$GOPATH结构 - CI/CD 环境中务必显式设置，避免因基础镜像
GO111MODULE默认为auto导致构建不一致 - Windows 用户注意：PowerShell 中用
$env:GO111MODULE="on"，CMD 中用set GO111MODULE=on，别漏掉引号
GO111MODULE=off 仅适用于老项目迁移过渡
设成 off 就彻底退回到 GOPATH 模式：所有 go 命令忽略 go.mod，不生成 go.sum，go get 直接写入 $GOPATH/src。这不是“兼容旧习惯”，而是主动放弃模块特性。
使用场景极少：比如你正在维护一个 Go 1.9 项目，团队尚未统一升级工具链，且暂时不打算引入版本控制语义；或者调试某个严重依赖 $GOPATH 路径硬编码的遗留脚本。
- 一旦项目已有
go.mod，再设GO111MODULE=off会导致go list -m all报错not using modules -
go mod vendor在off模式下直接不可用，命令不存在 - 某些 IDE（如 VS Code 的 Go 扩展）会静默忽略
go.mod，补全和跳转按 GOPATH 路径解析，造成开发体验割裂
GO111MODULE=auto 的坑：$GOPATH/src 下的假模块
auto 是 Go 1.16 之前的默认值，现在仍被很多文档沿用，但它在边界 case 下行为模糊。最典型的是：你在 $GOPATH/src/example.com/foo 目录下执行 go mod init，生成了 go.mod，但后续 go build 仍可能走 GOPATH 模式——因为 auto 发现你在 $GOPATH/src 里，就认为“这是老式布局”，不启用模块。
这导致依赖不走 replace、exclude 不生效、go.sum 不更新，甚至 go run main.go 和 go build 行为不一致（前者可能绕过模块检查）。
- 验证是否真启用了模块：运行
go env GOMOD，输出应为当前目录下的go.mod绝对路径，而不是空或go.mod不存在提示 -
go list -m在auto模式下可能返回command-line-arguments而非模块名，说明模块未激活 - 不要依赖文档说“auto 就够了”，只要项目根目录有
go.mod，就该设on
go mod init 后 GO111MODULE 状态必须匹配
go mod init 只是生成文件，不改变环境变量。如果此时 GO111MODULE=off，那 go.mod 就是废文件；如果 GO111MODULE=on 但没配 GOPROXY，又可能因私有域名解析失败卡住。
实操建议：初始化后立刻验证模块是否真正接管构建流程。
- 执行
go build -v，观察输出里是否有finding example.com/bar@v1.2.3这类模块解析日志；若只有github.com/user/pkg路径打印，说明还在 GOPATH 模式 - 检查
go.sum是否随go get自动更新；没更新？大概率GO111MODULE没生效 - 跨平台协作时，把
export GO111MODULE=on加进项目根目录的.env（配合 direnv）或 CI 脚本，比靠人记更可靠
模块不是开关，而是 Go 工具链的一层约束系统。环境变量设错，整个依赖解析链条就脱钩——这点比 go.sum 校验失败还难排查，因为错误往往静默发生。
