go mod init失败、go mod tidy卡住、replace失效等问题源于未识别go modules的行为边界：go111module=off需手动开启，国内需配置goproxy代理，replace要求路径严格匹配且非符号链接，vendor需显式启用-mod=vendor或清空goflags。
Go 环境搭建本身不难，但依赖管理出问题时，go mod tidy 报错、go get 卡住、本地模块替换失效——这些不是配置没到位，而是你没意识到 Go Modules 的行为边界和隐式约束。
go mod init 失败：GO111MODULE=off 是默认陷阱
执行 go mod init myapp 报错 go: modules disabled by GO111MODULE=off，说明当前 shell 会话里 Go Modules 被显式关掉了。这不是版本旧，而是环境变量覆盖了默认行为（Go 1.16+ 默认开启，但某些旧 shell 配置或 CI 环境仍保留 GO111MODULE=off）。
-
go env -w GO111MODULE=on立即生效，但仅对当前用户全局有效 - 检查
go env | grep GO111MODULE，确认输出是GO111MODULE="on" - 如果用 Docker 或 CI 脚本，必须在运行前显式设置，不能依赖“默认”
- Windows PowerShell 用户注意：
go env -w写入的是用户级配置，CMD 和 PowerShell 可能读取不同 registry 路径，建议统一用$env:GO111MODULE="on"临时设
go mod tidy 卡在 proxy.golang.org 或超时
国内常见现象：命令卡住几秒后报 Get "https://proxy.golang.org/..." dial tcp: i/o timeout。这不是网络断了，而是 Go 默认代理不可达且未 fallback 到 direct 模式。
- 先试
go env -w GOPROXY=https://goproxy.cn,direct（推荐清华、阿里云或 goproxy.cn，2026 年仍稳定） - 加
-x参数观察真实请求：go mod tidy -x，能看到它试图 fetch 哪个 module 的哪个 version - 若某私有模块（如
git.internal.company.com/lib）始终失败，需额外配go env -w GONOPROXY=git.internal.company.com - 避免混用
GOPROXY=direct—— 这会让所有模块走 git clone，慢且易因 SSH key 或权限失败
replace 替换本地模块后 go build 仍用远程版本
写完 go mod edit -replace example.com/foo=../foo，go mod tidy 也成功了，但 go run . 运行时还是 panic：找不到 foo.NewClient() —— 说明编译根本没用你本地改的代码。
- 确认
../foo目录下有有效的go.mod文件，且module行声明的路径与 replace 左侧完全一致（包括大小写、斜杠方向） - 执行
go list -m all | grep foo，输出应显示example.com/foo v0.0.0-00010101000000-000000000000 => ../foo，否则 replace 没生效 - 如果
../foo是 symlink，Go 不识别，必须是真实目录路径 -
go build时加-work参数可看到临时构建目录，检查里面解压的 module 是否来自../foo而非 cache
vendor 目录生成后 go build 不生效
运行 go mod vendor 生成了 vendor/，但 go build 依然从 $GOPATH/pkg/mod 拉包，vendor 形同虚设。
- Go 1.14+ 默认启用 vendor 模式，但前提是项目根目录存在
vendor且go.mod里没有// +build ignore类注释干扰 - 验证是否启用：
go env | grep GOFLAGS，若含-mod=mod，则强制忽略 vendor；清掉它：go env -w GOFLAGS="" - 更稳妥的方式是显式指定：
go build -mod=vendor，尤其在 CI 中避免隐式行为差异 - 注意
vendor/modules.txt必须与go.mod一致，手动删改 vendor 后务必重新go mod vendor，否则 checksum 校验失败
真正容易被忽略的，是 Go Modules 的“静默降级”行为：当某个依赖的特定版本在 proxy 上不可用时，它不会报错，而是自动尝试更旧版本甚至主干 commit，最终构建成功但逻辑已偏移。遇到诡异行为，先跑一遍 go list -m all 对照预期版本号。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
