go mod init失败因模块路径非法或不在根目录；go get需用vx.y.z等有效格式；go mod tidy会删未引用的replace包；ci中vendor仍依赖goproxy校验。
go mod init 初始化失败：找不到 go.mod 或模块路径写错
初始化项目时 go mod init 报错，常见原因是当前目录不在 GOPATH/src 下（旧习惯残留），或模块名用了非法字符（比如带空格、下划线、大写字母开头的路径）。Go Modules 不依赖 GOPATH，但模块路径必须是合法的 DNS 风格标识符，推荐用小写字母 + 连字符 + 点号，例如 github.com/username/project-name。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 进到项目根目录再执行
go mod init github.com/username/myapp，别在子目录里 init - 如果已有
go.mod但路径不对，直接编辑它改module行，不要重复 init - 本地开发又不想推远程？用
example.com/myapp这类占位域名完全合法，Go 不校验真实性
go get 拉不到预期版本：@ 符号后面跟什么才有效
go get 默认拉最新 tag 或主干，但实际项目中你常需要固定版本。关键不是“加不加 @”，而是 @ 后面的格式是否被 Go 识别为版本标识——只有 vX.Y.Z（含 v）、commit-hash、branch-name 这三类能生效。写成 @1.2.3（缺 v）或 @main（main 是分支，但某些仓库没这个分支）都会静默失败或拉错。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 查可用版本：先
go list -m -versions github.com/some/pkg - 锁死语义化版本：用
go get github.com/some/pkg@v1.4.2，不是@1.4.2 - 临时调试用 commit：确保 hash 是完整 40 位，短 hash（如
@abc123）可能匹配多个，行为不确定 - 慎用
@master：它不是稳定锚点，下次go mod tidy可能自动升级到新提交
go mod tidy 清掉不该清的包：replace 和 exclude 的作用边界
go mod tidy 会删掉 go.mod 里没被任何 .go 文件 import 的包，但如果你用 replace 替换本地路径，而该路径下没实际 import，它照样删——因为 replace 不等于引用。exclude 更危险：它让 Go 完全忽略某版本范围，但若其他依赖间接要求被 exclude 的版本，构建可能失败，且错误信息里不会提示 exclude 是元凶。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
replace只用于开发调试，上线前务必删掉或改成真实版本；确认替换生效：go list -m -f '{{.Replace}}' github.com/xxx -
exclude几乎不用，除非你明确知道某个版本有严重 bug 且无法绕过（比如被深层依赖硬编码 require） - 想保留一个暂时没被 import 但未来要用的包？在任意 .go 文件里加一行
import _ "github.com/xxx"（空导入），tidy就不会删它
CI 构建失败：vendor 目录和 GOPROXY 的协同问题
启用 go mod vendor 后，本地构建没问题，但 CI 上仍报找不到包，大概率是 GOPROXY 设置冲突。vendor 目录只影响 go build 时的源码查找路径，不影响 go mod download 或 go mod verify——而 CI 通常会先跑 go mod download 校验 checksum，这时仍要走代理。如果 GOPROXY 设成私有地址但不可达，或设成 direct 却网络受限，就会卡住。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- CI 脚本里显式设置：
GOPROXY=https://proxy.golang.org,direct（fallback 到 direct 是安全兜底） - 用
go mod vendor后，检查vendor/modules.txt是否包含所有依赖，别只信目录存在 - 禁止在 CI 中执行
go mod tidy或go get：vendor 应该是确定态，动态操作会引入不确定性
模块路径拼写、@ 后版本格式、replace 的生命周期、GOPROXY 在 vendor 场景下的真实作用——这四个点，任一个模糊都可能让依赖管理从“自动”变成“玄学”。
