离线环境必须预下载模块缓存，因go mod download和go get默认依赖网络，断网时直接失败；唯一可行路径是在有网机器执行go mod download拉取全部依赖至$GOPATH/pkg/mod/cache，打包后拷贝到离线机并设GOPROXY=direct，确保构建全程不联网。
离线环境必须预下载模块缓存
没有公网时，go mod download、go get 会直接失败，因为默认依赖远程索引和校验。唯一可行路径是：在有网机器上提前拉取完整依赖树并打包带走。
- 确保目标项目
go.mod和go.sum已提交且稳定，不要含未提交的本地修改 - 在联网机器执行：
go mod download -json查看将拉取哪些模块及其版本（便于核对完整性） - 运行
go mod download，它会把所有依赖写入$GOPATH/pkg/mod/cache目录 - 打包整个
pkg/mod/cache目录（注意保留目录结构），拷贝到离线机器对应位置 - 离线机器需设置
GOPROXY=direct，否则 Go 仍会尝试连接代理地址
构建镜像时跳过网络依赖的 Dockerfile 写法
CI/CD 或生产服务器常无外网权限，Docker 构建阶段不能触发任何网络请求。关键在于把依赖下载和编译拆开，且不依赖 go build 自动 fetch 行为。
- 第一阶段（builder）中，
COPY go.mod go.sum .必须放在COPY . .之前，否则缓存失效 -
RUN go mod download要紧随其后，且不能带任何-u或@latest参数——这些都会触发远程查询 - 禁用 GOPROXY：
ENV GOPROXY=direct，避免构建时仍尝试连接goproxy.cn等地址 - 若使用 Alpine 基础镜像，记得
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/，否则静态二进制可能因证书缺失无法访问 HTTPS 私服
私有模块校验失败时的处理边界
离线环境下 checksum mismatch 错误更常见，根源不是网络不通，而是 go.sum 记录的哈希与本地缓存内容不一致——通常因缓存被手动篡改或跨平台复制时文件换行符变化。
- 不要用
go clean -modcache，它会清空你辛苦带过来的全部缓存 - 优先检查
go.sum中对应模块行末是否多出空格或 Windows CRLF 换行符 - 临时绕过校验仅限调试：
go build -mod=readonly -modcacherw，但必须配合已验证的go.sum - 若私有模块托管在 GitLab/GitHub Enterprise，确认其域名已加入
GOINSECURE（如export GOINSECURE="git.internal.company"），否则 TLS 验证失败也会表现为 checksum error
交叉编译产物无法运行？检查 CGO 和 libc 兼容性
离线部署常需在 x86_64 构建 ARM64 二进制，但默认开启 CGO_ENABLED=1 时，生成的二进制会动态链接宿主机 libc，导致在目标环境报 not found。
立即学习“go语言免费学习笔记（深入）”；
- 纯静态链接：构建前设
CGO_ENABLED=0，适用于绝大多数 HTTP/gRPC 服务 - 若必须用 cgo（如调用 OpenSSL/C 原生库），则需在 builder 阶段安装对应架构的
musl-dev（Alpine）或libc6-dev（Debian），且 final 镜像必须包含对应 runtime 库 - 验证方式：
file your-binary输出含statically linked才真正离线可用；含dynamically linked则需同步部署 so 文件
go.sum 文件本身也是“有状态”的，它不是只读清单，而是校验快照。一旦缓存目录被复制、解压或挂载方式改变（如 NTFS vs ext4 的权限/时间戳差异），就可能触发校验失败——这时修 go.sum 比重下缓存更安全。 
