go mod init 报错因模块路径不合法，必须为小写、含点号的类url格式（如example.com/myapp），禁用本地路径、大写字母、空格或下划线；正确做法是显式指定合法路径。
go mod init 为什么报错 module path 不合法
模块路径必须是可解析的域名或有意义的标识符，不能是本地路径或纯数字。常见错误是直接在项目根目录执行 go mod init 而不带参数，Go 会尝试从父目录推导路径，结果生成类似 go mod init /home/user/myproj 这种非法路径。
- 正确做法：显式指定模块名，比如
go mod init example.com/myapp（即使不发布，也建议用占位域名） - 若项目已托管在 GitHub，直接用仓库地址：
go mod init github.com/username/repo - 模块名中不能含大写字母、空格、下划线；推荐全小写 + 连字符（如
go mod init my-cli-tool） - 初始化后检查
go.mod文件第一行是否为module example.com/myapp，不是module .或绝对路径
依赖自动下载但 build 失败，提示 missing required module
这通常不是网络问题，而是 go.mod 中记录了某个间接依赖（// indirect），但该模块在当前 Go 版本下已被移除、重命名，或其自身依赖链断裂。
- 运行
go mod graph | grep "missing"可定位具体缺失模块 - 优先尝试
go mod tidy—— 它会重新解析依赖树，删掉未引用的间接依赖，并补全缺失项 - 如果仍失败，可能是某依赖要求更高 Go 版本：检查该模块的
go.mod中go 1.20等声明，再确认本地go version - 慎用
go get -u全量升级：可能引入不兼容变更；应改用go get some/module@v1.2.3显式指定版本
vendor 目录生成后 go build 仍去拉远程包
go build 默认不强制使用 vendor/，除非明确启用 vendor 模式。即使有 vendor 目录，Go 仍会校验 go.mod 和远程 checksum，网络不通时会报错。
- 启用 vendor 模式：加
-mod=vendor参数，例如go build -mod=vendor - 确保
vendor/modules.txt存在且内容完整（由go mod vendor生成） - 注意：Go 1.14+ 默认开启
GOPROXY=direct时仍可能触发校验请求；离线构建建议设GOPROXY=off - CI 环境中，若用
go mod vendor，记得把vendor/提交进 Git —— 否则其他机器拉代码后go mod vendor可能因网络失败
升级某个依赖时，go mod upgrade 却没生效
go get 和 go mod upgrade 行为不同：go mod upgrade 是实验性命令（Go 1.22+），默认只升一级次要版本；而多数人误以为它等价于“全部更新到最新”。
- 想升级单个模块到指定版本：用
go get example.com/lib@v2.1.0 - 想升级到最新稳定版（遵守 semver）：用
go get example.com/lib@latest - 升级后务必运行
go mod tidy，否则go.mod中可能残留旧版本或冗余// indirect条目 - 升级后测试要覆盖 import 路径变更（如 v2+ 模块需带
/v2后缀）、API 是否有 breaking change
模块依赖看似只是几行文本，但 go.sum 校验、间接依赖隐式引入、vendor 模式开关这些细节，任何一个卡住都会让构建停在 CI 或同事电脑上。别跳过 go mod verify 和本地 go build -mod=readonly 验证。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
