go111module=on是硬性前提，必须启用模块模式；module路径须匹配仓库地址；私有模块需配置goprivate跳过代理；go.mod所在目录为模块根，目录结构须规范。
GO111MODULE=on 是硬性前提，不是可选项
只要项目里有 go.mod，就必须让 Go 工具链明确知道你在用 Modules。设成 auto 时，它会检查当前路径是否在 $GOPATH/src 下——比如你在 /tmp/myapp 初始化，go build 直接报 no required module provides package；设成 off 更糟，go mod tidy 直接失效，所有依赖管理退回到 GOPATH 黑盒时代。
执行这条命令一劳永逸：go env -w GO111MODULE=on
验证方式：go env GO111MODULE 输出必须是 on，不是空、不是 auto。
module 路径必须匹配仓库地址，不能按本地目录起名
go mod init 后生成的 module 行不是随便写的别名，它决定了别人 import 你的包时用什么路径，也决定了 go.sum 校验和是否能对上。常见错误是：项目放在 /home/user/myproject，就写 module myproject——这会导致外部项目 import "myproject" 失败，且 go get 拉不到你发布的版本。
正确做法：
- 如果你托管在 GitHub，就写
module github.com/yourname/myproject - 如果是公司内网 Git，写
module git.internal.company.com/team/myproject - 如果只是本地开发没打算公开，也建议用占位域名如
module example.com/myproject，避免后续迁移成本
改完后立刻运行 go mod tidy，否则旧 import 路径可能残留导致构建失败。
私有模块不配 GOPRIVATE 就会 401 或 404
没设 GOPRIVATE 时，Go 默认把所有模块都扔给 GOPROXY 去拉——包括 git.internal.company.com/lib/foo 这种私有地址。结果就是 go mod tidy 卡住，报错：reading git.internal.company.com/lib/foo/go.mod: 401 Unauthorized。
解决方法是显式告诉 Go 哪些域名跳过代理：
- 单个域名：
go env -w GOPRIVATE=git.internal.company.com - 通配符（推荐）：
go env -w GOPRIVATE="*.internal.company.com" - 多个域名用逗号分隔：
go env -w GOPRIVATE="git.internal.company.com,github.com/myorg"
注意：这里填的是域名，不是完整 URL，也不带 https://；设完之后，replace 指令和 SSH 克隆才能正常工作。
非标准目录结构下，go build 的路径逻辑容易误判
Go 不认“自定义 src 目录”这种结构。比如你把代码全塞进 project/src/main.go，Go 会认为包路径是 project/src，而不是你期望的 project。结果 import "project" 失败，go run main.go 报 cannot find package，IDE 里符号全红。
关键原则：
-
go.mod所在目录就是模块根，所有相对路径以此为基准 -
cmd/、internal/、pkg/这些目录必须直接放在模块根下，不能套多层 - 要跑
go run cmd/server/main.go，前提是cmd/server是合法包路径，即该目录下有main.go且 package 是main
最简验证法：cd 进 go.mod 所在目录，执行 go list ./... —— 如果输出一堆包路径，说明结构被识别了；如果只报错或没输出，大概率是目录嵌套过深或 package 声明不对。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
