必须配置goproxy，推荐https://goproxy.cn,direct，否则国内无法正常拉取go模块；涉及私有模块需额外设置goprivate和gosumdb。
Go 环境能装上，但 go mod download 卡住或报错 timeout、no matching versions，根本不是安装问题，而是代理没配对——国内不配 GOPROXY，几乎没法正常拉依赖。
go version 能跑，但 go mod tidy 总失败
现象：命令行能识别 go version，但一执行 go mod tidy 就卡在 “Downloading” 或直接报错：Get \"https://proxy.golang.org/...\": dial tcp 216.58.200.49:443: i/o timeout。这不是你网络差，是 Go 默认用的是境外代理 https://proxy.golang.org，国内直连基本不可用。
- 必须手动设置国内可用的
GOPROXY，推荐https://goproxy.cn（稳定、免登录、支持私有模块 fallback） - 同时加
direct作为兜底，避免私有模块被误代理：go env -w GOPROXY=https://goproxy.cn,direct - 如果项目涉及公司内网模块，还得加
GOPRIVATE（比如go env -w GOPRIVATE=git.internal.company.com/*），否则代理会强行转发导致 404 - 验证是否生效：运行
go env GOPROXY，输出应为https://goproxy.cn,direct
Linux/macOS 下 /usr/local/go/bin 不在 PATH 中
现象：安装完 Go，go version 报 command not found。常见于 Linux 手动解压安装，或 macOS 用 tar 方式安装后没改 shell 配置文件。
- 确认 Go 是否真解压到
/usr/local/go（Linux/macOS 默认路径），用ls /usr/local/go/bin/go检查二进制是否存在 - 编辑对应 shell 配置文件：
~/.bashrc（bash）或~/.zshrc（zsh），追加一行：export PATH=$PATH:/usr/local/go/bin - 别忘了重载配置：
source ~/.zshrc（或source ~/.bashrc） - 注意：不要写成
export PATH=/usr/local/go/bin:$PATH（把系统原有 PATH 覆盖了），顺序错会导致ls、curl等命令找不到
VSCode 插件提示 “Tool gopls is not available”
现象：VSCode 打开 .go 文件，左下角一直显示 “Installing tools…” 或弹窗报 gopls 安装失败。本质是插件尝试用默认代理下载 Go 工具链，而你没配 GOPROXY。
- 先确保终端里
go env GOPROXY已正确设置（见第一个副标题） - VSCode 启动时读取的是它自己的 shell 环境，不是你终端当前环境 —— 如果你用桌面快捷方式启动 VSCode，它可能没加载
~/.zshrc；解决方法：从终端执行code .启动 VSCode - 或者，在 VSCode 设置中搜
go.toolsEnvVars，手动添加："GOPROXY": "https://goproxy.cn,direct" - 重启 VSCode 后，按
Ctrl+Shift+P→ 输入 “Go: Install/Update Tools”，勾选全部，点 OK —— 这次应该能顺利装完gopls、dlv等工具
go mod init 后 go.sum 出现 checksum mismatch
现象：go mod tidy 成功，但运行 go run 或 go build 时突然报错：verifying github.com/some/pkg@v1.2.3: checksum mismatch。这通常不是网络问题，而是本地缓存污染或校验服务器（GOSUMDB）策略冲突。
- 临时绕过校验（仅调试用）：
go env -w GOSUMDB=off，但不推荐长期关闭 - 更稳妥的做法是清空模块缓存并重试：
go clean -modcache，再go mod tidy - 如果公司用了私有校验服务，需设
go env -w GOSUMDB=sum.golang.org+https://sum.example.com - 注意：
go.sum文件不能手动删或改 —— 它由 Go 工具自动生成和维护，修改后下次go mod会报错
真正卡住人的从来不是“怎么装 Go”，而是代理链路没打通：从 GOPROXY 到 GOPRIVATE 再到 GOSUMDB，三者配合稍有偏差，go mod 就会静默失败。配完别只测 go version，一定要跑一次 go mod tidy 和 go run main.go 才算闭环。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
