go.mod是跨发行版一致性的唯一锚点，必须位于项目根目录且路径合法；未启用模块模式或go.mod位置错误会导致no required module提供package等错误，而非发行版差异所致。
go.mod 是跨发行版一致性的唯一锚点
不同 Linux 发行版（Ubuntu、CentOS、Alpine）上 go build 失败，90% 不是系统差异导致的，而是项目没启用模块模式，或 go.mod 没被正确识别。Go 工具链不关心你用的是哪个发行版，只认 go.mod 文件是否存在、路径是否合法、内容是否规范。
常见错误现象：no required module provides package、cannot find module providing package、import path not found —— 这些都不是发行版问题，是当前目录没 go.mod，或 go.mod 被放在子目录里，或项目根目录意外落在 $GOPATH/src 下触发了降级 GOPATH 模式。
- 新建项目第一件事必须是：在空目录下执行
go mod init example.com/myapp（域名前缀不能是./或../） -
go.mod必须位于项目根目录，且该目录不能是$HOME/go/src/xxx这类传统 GOPATH 路径 - 提交时必须保留
go.mod和go.sum—— 它们共同锁定了依赖的 exact commit hash，与发行版无关 - CI 流水线里如果用
go test ./报错，先确认是否在含go.mod的目录下执行，而不是进cmd/或internal/子目录单独运行
Linux 发行版差异只影响 cgo 和构建工具链
真正会被发行版“卡住”的地方，只有 cgo 依赖和交叉编译场景。比如你在 Ubuntu 上用 go build 引入了 github.com/mattn/go-sqlite3，它默认启用 cgo；到了 Alpine 容器里跑，就会报 exec: "gcc": executable file not found —— 因为 Alpine 默认没装 gcc，而 Ubuntu 通常预装了。
这不是模块管理的问题，是构建环境不一致。解决方案不是改 go.mod，而是统一构建方式：
- 纯 Go 项目（无 cgo）：直接
CGO_ENABLED=0 go build，所有发行版行为一致 - 含 cgo 的项目：别在宿主机构建，改用 Docker —— 例如
docker run --rm -v $(pwd):/work golang:1.25-alpine sh -c "cd /work && CGO_ENABLED=1 go build -o app ." - 若必须本地构建，确保各发行版都装好对应 C 工具链：
apt install build-essential（Ubuntu）、yum groupinstall "Development Tools"（CentOS）、apk add build-base（Alpine）
go env GOROOT 和 GOPATH 在发行版间必须保持干净
不同发行版用户容易各自用包管理器装 Go（apt install golang-go vs dnf install golang），结果 go env GOROOT 输出五花八门：/usr/lib/go-1.21、/usr/lib/golang、/usr/local/go……这些路径差异会导致 gopls 找不到 SDK、CI 构建时缓存失效、甚至 go install 写入错误位置。
解决办法只有一个：所有发行版统一用官方二进制安装，路径固定为 /usr/local/go：
- 下载地址始终是
go.dev/dl，例如go1.25.4.linux-amd64.tar.gz - 解压命令统一：
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go*.tar.gz - PATH 设置统一：
export PATH=/usr/local/go/bin:$PATH（写入~/.bashrc或/etc/profile.d/go.sh） - 验证命令统一：
go version和go env GOROOT输出必须都是/usr/local/go
go.sum 校验失败常被误判为发行版问题
某台机器上 go mod download 成功，另一台却卡在 verifying github.com/some/pkg@v1.2.3: checksum mismatch —— 看似是发行版差异，实则是其中一台机器的 GOSUMDB 没关，或代理配置不一致。
国内网络环境下，sum.golang.org 基本不可达，而不同发行版的 shell 默认配置可能让 go env 读取到不同值。必须显式禁用校验：
- 执行：
go env -w GOSUMDB=off - 同时确保代理设置一致：
go env -w GOPROXY=https://goproxy.cn,direct - 不要只设
GOPROXY就以为万事大吉 ——GOSUMDB=off是绕过校验的关键开关 - 验证：
go env GOSUMDB GOPROXY，两台机器输出必须完全一致
go.mod 当成契约，把 GOROOT 当成常量，把 GOSUMDB=off 当成必需项。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
