私有模块拉取失败的根本原因是goprivate未显式配置，导致go默认通过proxy.golang.org访问git.internal.company/project等私有路径而返回404；必须在所有开发机和ci中执行go env -w goprivate=git.internal.company,github.com/myorg/private，支持通配符（如*.internal.company），且需注意引号避免shell展开。
私有模块拉取失败：GOPRIVATE 必须显式配置
团队内部模块（如 git.internal.company/project）默认会被 Go 的公共代理（proxy.golang.org）拦截，导致 go get 报错 module git.internal.company/project: reading https://proxy.golang.org/...: 404 Not Found。这不是网络问题，而是 Go 默认强制走代理的策略。
解决方式只有一条：在所有开发机和 CI 环境中设置 GOPRIVATE 环境变量，明确告诉 Go 哪些域名下的模块跳过代理和校验：
go env -w GOPRIVATE=git.internal.company,github.com/myorg/private- 支持通配符：
go env -w GOPRIVATE="*.internal.company"（注意引号，避免 shell 展开） - CI 中需在构建脚本开头设置，不能依赖开发者本地配置
替换 fork 或临时修复：用 replace 而不是改 import 路径
当你需要基于上游库（如 github.com/uber-go/zap）打补丁、或使用内部镜像时，直接修改代码里的 import 语句会破坏可移植性，且 go mod tidy 会把它“修正”回去。
正确做法是在 go.mod 中添加 replace 指令：
replace github.com/uber-go/zap => ./forks/zap
或指向私有 Git 地址：
replace github.com/uber-go/zap => git.internal.company/forks/zap v1.25.0
注意：
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
-
replace只影响当前模块构建，不改变下游依赖看到的路径 - 如果替换成本地路径（如
./forks/zap），该路径必须存在且含有效go.mod - 不要在生产发布前忘记删掉
replace——它不会被下游自动继承
CI 构建失败：go.sum 校验被绕过或未提交
CI 报错 verifying github.com/some/lib@v1.2.3: checksum mismatch，大概率是因为 go.sum 文件没进 Git，或有人在 CI 中执行了 go mod download 后又提交了新生成的 go.sum。
go.sum 不是“生成文件”，而是**必须由开发者运行 go mod tidy 后手动提交的校验快照**。它的作用是确保每次下载的包内容和首次一致。
- 禁止在 CI 中运行
go mod download后再git add go.sum—— 这会让本地go build失败 - CI 流程只需执行
go build或go test，Go 会自动校验go.sum；若失败，说明本地和 CI 的依赖来源不一致 - 团队应把
go.sum加入 .gitignore 的检查清单，防止误删
多人协作时模块路径混乱：发布标签必须带 v 前缀
团队成员执行 go get mycompany.com/core@v1.0.0 失败，常见原因是模块发布时打了 1.0.0 标签而非 v1.0.0。Go Modules 严格要求语义化版本标签以 v 开头。
修复方法：
- 重打带
v的 tag：git tag v1.0.0 && git push origin v1.0.0 - 已发布的错误 tag 无法删除（尤其在企业 Git 平台），只能补发
v1.0.1并通知团队切换 - 模块路径（
go.mod第一行）一旦写入，就不能随意变更——否则所有下游go get都会 404
最易被忽略的是：模块路径不等于 Git 仓库地址，但必须能通过 go get 导入。例如仓库在 git.internal.company/backend，模块路径却设为 mycompany.com/backend，那就必须配置好对应域名的 Git 重定向或代理，否则拉取失败。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
