go modules初始化失败主因是未显式指定合法module path，导致go推导出错误路径（如myproject），正确做法是执行go mod init github.com/username/repo等符合语义的类url路径。
Go Modules 初始化失败：go mod init 报错或生成错误 module path
执行 go mod init 时如果当前目录不在 $GOPATH/src 下，且未显式指定 module 名称，Go 会尝试从当前路径推导——比如在 /home/user/myproject 下直接运行 go mod init，可能生成 module myproject，但实际你希望是 module github.com/username/myproject。这会导致后续 go get 拉取依赖时解析失败，尤其涉及私有仓库或语义化版本时。
正确做法是：明确指定符合 Go 模块命名惯例的路径，通常是代码托管地址（即使尚未 push）：
- 公开项目：用
go mod init github.com/username/repo - 私有项目（GitLab / 自建 Git）：用
go mod init gitlab.example.com/group/project - 本地开发暂无远程地址：至少用带域名前缀的名称，如
go mod init example.com/myproject，避免纯名称（如myproject）
模块名一旦写入 go.mod 就不建议随意修改，否则已发布的依赖引用会失效。
go get 添加依赖后 go.mod 没更新或版本不一致
go get 默认行为已变：Go 1.16+ 默认只更新 go.mod，不自动下载源码到本地缓存（$GOPATH/pkg/mod），也不触发 go build 所需的 vendor 或 checksum 验证。常见表现是 go.mod 中出现 // indirect 标记，或 go list -m all 显示版本与预期不符。
确保依赖被正确解析和锁定：
- 添加新依赖：用
go get github.com/sirupsen/logrus@v1.9.3（显式指定版本更可控） - 升级已有依赖：先删掉
go.sum中对应行（或整个文件），再运行go get -u=patch github.com/sirupsen/logrus - 强制同步：执行
go mod tidy，它会删掉未使用的依赖、补全缺失的间接依赖，并重写go.sum
注意：go get 不会自动升级子依赖，除非加 -u；而 go mod tidy 是唯一能保证 go.mod 和代码 import 严格一致的命令。
私有仓库拉取失败：x509 certificate signed by unknown authority 或 403
Go 默认通过 HTTPS 访问模块代理（proxy.golang.org）和校验源，但私有 Git 服务器（如 GitHub Enterprise、GitLab Self-Hosted）常因证书或鉴权问题中断。
分场景处理：
- 自签名证书：设置
GOPRIVATE=gitlab.example.com（跳过代理和校验），并配export GIT_SSL_NO_VERIFY=1（仅限测试环境） - 需要 token 鉴权的私仓：在
~/.netrc中添加凭据：machine gitlab.example.com login gitlab-token password <your_token></your_token>，再确保GOPRIVATE包含该域名 - 完全离线环境：设
GOPROXY=direct并禁用校验：GOSUMDB=off，但必须自行保障模块完整性
验证是否生效：运行 go list -m github.com/private-org/private-lib，不应报 no required module provides package。
vendor 目录不更新或构建仍走 proxy
启用 go mod vendor 后，go build 默认仍可能绕过 vendor 目录去远程拉取——因为 Go Modules 的 vendor 模式不是“强制隔离”，而是“可选缓存”。关键开关是 -mod=vendor。
正确使用 vendor 流程：
- 生成 vendor：运行
go mod vendor（会创建vendor/并写入vendor/modules.txt） - 构建时启用：必须显式加参数，如
go build -mod=vendor ./cmd/app - CI/CD 中检查一致性：在
go mod vendor后加go mod verify，确保所有模块 checksum 匹配go.sum
容易忽略的一点：go mod vendor 不会包含测试依赖（_test.go 中 import 的包），若测试需要独立 vendor，得手动 go test -mod=vendor。
