go 1.16+ 不需手动设置 gopath，它仅用作模块缓存路径（$gopath/pkg/mod），不再影响构建；项目可放任意目录，只需执行 go mod init 并设正确模块路径（如 github.com/you/project）。
go version 能跑出来，但 GOPATH 还用不用？
2026 年的 Go 项目，GO111MODULE=on 是默认行为，GOPATH 已退化为缓存下载包的路径（$HOME/go/pkg/mod），不再参与构建逻辑。你不需要手动设置 GOPATH，也不该把它当作工作区根目录来组织代码。
常见错误现象：go run main.go 报错 no required module provides package，本质是没执行 go mod init，跟 GOPATH 无关。
- 验证方式：运行
go env GOPATH，看到路径只是说明模块缓存位置，不是开发目录 - 新建项目只需：
mkdir myapp && cd myapp && go mod init github.com/you/myapp - 如果仍手动设
GOPATH并把项目放进去，反而容易和旧教程混淆，导致go get行为异常
cmd/、internal/、pkg/ 目录到底什么时候建？
大厂真实项目里，这些目录不是“标配”，而是“按需出现”的信号灯：
-
cmd/：只在项目提供多个可执行程序时才建（比如cmd/server和cmd/cli），单体服务直接放main.go在根目录 -
internal/：当某组代码明确不希望被外部 import（比如数据库迁移脚本、私有中间件），才移入internal/；否则一律平铺，如storage/、api/ -
pkg/：已被主流放弃。写import "github.com/you/project/storage"比import "github.com/you/project/pkg/storage"少敲 4 个字符，且语义更直白
反例：刚初始化就建好三层目录，结果半年后 pkg/ 下只有两个空文件夹——这不是工程规范，是目录幻觉。
go.mod 里的 module 名怎么起才不踩坑？
module 名不是随便填的，它直接影响别人 import 的路径和未来迁移成本：
- 必须是完整 URL 形式（如
github.com/your-org/project-name），不能用本地路径或相对路径 - 避免带
v1、main、dev等版本/状态词（github.com/your-org/project-v1会导致后续升级 v2 时路径断裂） - 如果项目将来要开源，现在就定好域名归属；若属公司内网，用内部 Git 地址（如
git.yourcorp.com/backend/auth），别用localhost或./
典型错误：go mod init myproject → 后续别人 import 时得写 import "./myproject"，根本无法构建。
为什么你的 IDE 总标红 “cannot find package”？
不是代码写错了，大概率是 Go 工具链没识别到当前模块上下文：
- 确保终端在项目根目录（含
go.mod的那层），再运行go list -m，应输出你的 module 名 - VS Code 用户检查右下角 Go 状态栏，确认显示的是 “Go (GOPATH)” 还是 “Go (Modules)” —— 必须是后者
- IntelliJ IDEA 需在 Settings → Languages & Frameworks → Go → GOPATH 中取消勾选 “Enable GOPATH mode”
最隐蔽的坑：项目放在 OneDrive / iCloud / WSL 跨文件系统路径下，go mod 缓存可能失效，表现为反复提示找不到依赖——换到纯本地 NTFS/ext4 路径重试。
go.mod 里每一条 replace 是否都有明确的上线倒计时。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
