离线搭建Go环境必须提前准备go二进制包、golang.org/x/等预编译模块（通过go mod download获取）、可选的go.dev离线文档；需正确配置GOROOT、PATH、GOPATH并写入/etc/profile.d/；构建时设GOPROXY=direct、GOSUMDB=off，用-mod=readonly确保不联网。

离线环境必须提前准备哪些文件

离线搭建 Go 环境的核心前提是：所有依赖项必须在联网机器上完整下载并拷贝过来。缺一不可的是：go 二进制安装包（对应目标系统架构）、GOPATH 下可能需要的预编译依赖（如 golang.org/x/... 模块），以及可选但强烈建议的 go.dev 文档离线包。

常见踩坑点是只下载了 go1.22.3.linux-amd64.tar.gz，却没处理 golang.org/x/net 这类标准库扩展——它们不会随主包自动包含，且在离线 go build 时会因无法 go get 直接报错：module github.com/golang/net@latest found (v0.28.0), but does not contain package golang.org/x/net/http2。

• 去 https://www./link/81836b7cd16991abb7febfd7832927fd 下载与目标系统完全匹配的 go$VERSION.$OS-$ARCH.tar.gz（例如 go1.22.3.linux-arm64.tar.gz）
• 用一台联网的同版本 Go 环境，执行：

  go mod download -x golang.org/x/net golang.org/x/sys golang.org/x/text golang.org/x/exp

  ，然后把整个 $GOPATH/pkg/mod 目录打包带走（注意保留目录结构）
• 若需本地文档，运行 godoc -http=:6060 -goroot /path/to/go 并用爬虫或浏览器插件保存静态页（官方已弃用 godoc 命令，但离线场景仍可用）

解压后如何正确配置环境变量

解压 go 包后不能直接运行 go version，因为 GOROOT 和 PATH 未生效。关键不是“加到 ~/.bashrc”，而是确保所有 shell 会话（包括非登录 shell、CI 工具、IDE 终端）都能读取到。

最稳妥做法是写入系统级配置，并验证是否被子进程继承：

• 解压到固定路径，例如：

  sudo tar -C /usr/local -xzf go$VERSION.linux-amd64.tar.gz

• 在 /etc/profile.d/golang.sh 中写入：

  export GOROOT=/usr/local/go
  export PATH=$GOROOT/bin:$PATH
  export GOPATH=$HOME/go
  export PATH=$GOPATH/bin:$PATH

• 执行 source /etc/profile.d/golang.sh 后，用 env | grep -E 'GO(R|P)' 确认变量存在；再新开一个终端，运行 go env GOROOT 验证是否生效

离线构建项目时如何避免 module lookup 失败

即使有 go.mod，离线 go build 仍可能卡在 verifying github.com/sirupsen/logrus@v1.9.3 或提示 unknown revision。这是因为 Go 默认启用 GO111MODULE=on 且尝试连接 proxy 和 checksum database。

必须显式关闭网络校验并强制使用本地缓存：

• 设置：

  export GOPROXY=direct
  export GOSUMDB=off
  export GOINSECURE="*"

  （GOINSECURE 仅当模块来自私有 Git 时才需，普通离线场景可省略）
• 确认项目根目录下有完整的 go.sum 文件（它应在联网时就生成好）；若缺失，需在联网机上先 go mod tidy && go mod verify，再拷贝整个项目目录
• 首次离线构建建议加 -mod=readonly 参数：

  go build -mod=readonly -o myapp ./cmd/myapp

  ，防止意外触发 go mod download

验证是否真正离线可用

很多人以为 go version 成功就代表环境 OK，但实际项目往往在 go test 或调用 cgo 时失败。验证必须覆盖真实使用路径。

最简有效验证组合：

• 运行：

  go version && go env GOPATH GOROOT && go list std | head -5

  （确认标准库可枚举）
• 创建最小测试项目：

  mkdir /tmp/offline-test && cd /tmp/offline-test
  go mod init offline-test
  echo 'package main; import "fmt"; func main() { fmt.Println("ok") }' > main.go
  go build -o test-bin .

• 执行 ./test-bin 输出 ok，再删掉 go.mod 和 go.sum 重试 —— 若仍成功，说明未误触网络；若失败，则说明某处隐式依赖了外部模块

真正麻烦的永远不是 go 本身，而是你项目里某个 import "gitlab.example.com/internal/util" 的私有路径，或者 cgo 依赖的本地 C 库头文件缺失。这些必须在联网阶段就全部 resolve 并打包进来。