go 1.11后项目必须配置go mod环境，核心是显式执行go env -w go111module=on和go env -w goproxy=https://goproxy.cn,direct，并确保vs code重启以透传环境变量，ci中还需缓存~/go/pkg/mod。
Go 1.11 之后的项目基本离不开 go mod，不配好模块环境，go build 或 go test 很可能直接报 go.mod file not found —— 这不是你代码写错了，是环境没认出这是个模块项目。
GO111MODULE=on 是硬性前提
新版 Go 默认是 auto 模式，它只在 $GOPATH/src 外且目录下有 go.mod 时才启用模块。但实际开发中，没人会把项目硬塞进 $GOPATH/src；更常见的是随手建个 ~/projects/myapp 就开干。这时候 auto 会退化成 off，导致依赖全走老路、go get 写死版本、vendor 同步失效。
必须显式设为 on：
go env -w GO111MODULE=on
这条命令写入用户级配置，一劳永逸。别信“默认就够用”，CI 流水线或新同事拉代码后首次运行，大概率卡在这一步。
GOPROXY 必须配，否则 go get 常驻超时
国内直连 proxy.golang.org 和 sum.golang.org 极不稳定，go mod download 卡住、go test 因拉不到 testify 类依赖而失败，都是高频现象。
推荐组合：
go env -w GOPROXY=https://goproxy.cn,direct
-
https://goproxy.cn响应快、缓存全，覆盖绝大多数公开模块 -
direct是 fallback：当模块未被代理收录（如私有 GitLab 仓库），Go 会跳过代理直连，避免误伤内部依赖
别用 https://proxy.golang.com.cn —— 它已停止维护，2025 年底起返回 403。
VS Code 中 gopls 启动失败，八成是环境变量没透传
VS Code 的 Go 插件依赖 gopls 提供代码补全、跳转、诊断。但它启动时用的是 VS Code 自己的环境变量副本，不是你终端里生效的那套。
常见症状：gopls 报 no modules found，或者编辑器里所有 import 都标红，但终端里 go build 正常。
解决方法只有两个：
- 重启 VS Code（确保它读取了最新
go env输出） - 在 VS Code 设置里手动指定 Go PATH：
"go.gopath"留空，"go.goroot"设为/usr/local/go（macOS/Linux）或C:\Program Files\Go（Windows）
别在 .vscode/settings.json 里硬写 GO111MODULE —— gopls 不读这个，它只认 go env 全局设置。
CI 流水线里 go mod tidy 失败，往往缺缓存或权限
GitHub Actions 或 GitLab CI 中跑 go mod tidy 报错，最常见原因不是网络，而是模块缓存没复用，每次从零下载。
正确做法是加缓存步骤（以 GitHub Actions 为例）：
- name: Cache Go modules
uses: actions/cache@v4
with:
path: ~/go/pkg/mod
key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
restore-keys: |
${{ runner.os }}-go-
注意三点：
- 路径必须是
~/go/pkg/mod，不是./pkg/mod——go mod默认写这里 -
key用go.sum哈希，比用go.mod更精准：依赖版本微调时，go.sum必变，缓存自然失效 - 如果项目用了私有模块（如
git.company.com/internal/lib），需额外配置 SSH agent 或 token，否则go mod download权限拒绝
模块管理不是“配一次就完事”，它嵌在构建、测试、IDE、CI 四个环节里，任一环掉链子，整个流程就会在某个看似无关的报错上卡住 —— 而那个报错，往往根本不提“模块”二字。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
