go build 编译出的二进制是否可靠、可复现、可迁移是关键问题，常见错误包括模块路径解析失败（cannot find package）、动态链接库缺失（error while loading shared libraries）、交叉编译后glibc版本不兼容（GLIBC_2.xx not found）及输出文件名逻辑混乱，根源在于Go Modules启用、CGO默认开启、包发现规则与平台适配未显式约束。
go build 是编译 Go 程序的主力命令，但直接敲 go build main.go 往往能跑通，却在交付、跨平台或团队协作时出问题。关键不是“能不能编译”，而是“编译出来的二进制是否可靠、可复现、可迁移”。
为什么 go build 在非模块目录下会报 “cannot find package”
常见现象：在任意子目录里执行 go build main.go，提示 cannot find package "myutils" 或 no required module provides package。
根本原因不是代码写错了，而是 go build 默认启用 Go Modules 模式，它只认两种路径：
— 当前目录（或其父目录）存在有效的 go.mod 文件；
— 且当前工作目录在该模块树内（即 go list -m 能输出模块名）。
如果你在 ~/tmp/test/ 下新建 main.go 就跑 go build，Go 不知道你属于哪个模块，依赖路径就全乱了。
实操建议：
• 进入项目根目录，先运行 go mod init myproject（模块名建议用实际域名或有意义的标识）；
• 所有 import 必须匹配 go.mod 中的 module 声明前缀，比如 module github.com/user/app，那么本地包就得写 import "github.com/user/app/utils"，不能写 import "./utils"；
• 临时测试单文件？用 go run -mod=mod main.go 强制启用模块解析，但别把它当长期方案。
go build 编译后运行报错 “error while loading shared libraries”
典型场景：Linux 上编译出 myapp，拷到另一台服务器运行，提示 error while loading shared libraries: libgo.so: cannot open shared object file。
这不是 Go 自身问题，而是 CGO 启用后默认生成动态链接二进制，依赖宿主机的 libc、libpthread 等系统库 —— 而不同 Linux 发行版的 libc 版本可能不兼容。
实操建议：
• 绝大多数纯 Go 项目不需要 CGO，加 CGO_ENABLED=0 再编译：CGO_ENABLED=0 go build -o myapp main.go；
• 如果必须用 CGO（比如调了 SQLite、OpenSSL），又想静态分发，得确认目标环境 libc 版本足够新，或改用 golang:alpine 镜像构建（Alpine 用 musl，更轻但兼容性略差）；
• macOS 默认静态链接，但用了 net 包仍可能触发系统 DNS 解析逻辑，需额外加 -tags netgo；
• Windows 上一般无此问题，但注意 GUI 程序要隐藏控制台窗口，得加 go build -ldflags "-H windowsgui"。
立即学习“go语言免费学习笔记（深入）”；
交叉编译 Linux 或 ARM64 二进制时，GOOS=linux 为啥还是失败
现象：在 macOS 上执行 GOOS=linux GOARCH=amd64 go build -o myapp main.go，结果编译成功，但放到 Ubuntu 容器里运行报 version `GLIBC_2.34' not found。
原因有两个层面：
— 表层：没关 CGO，导致链接了宿主机（macOS）不可用的 glibc 符号；
— 深层：即使关了 CGO，Go 1.20+ 默认用 ld 的 -buildmode=pie，而旧版 glibc 不支持 PIE 可执行文件。
实操建议：
• 最简稳解：CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o myapp main.go；
• ARM64 目标（如树莓派、AWS Graviton）用 GOARCH=arm64，不是 arm 或 aarch64；
• 若必须启用 CGO 交叉编译：
– macOS 用户装 x86_64-linux-gnu-gcc（brew install x86_64-linux-gnu-binutils x86_64-linux-gnu-gcc），再设 CC_x86_64_linux_gnu=x86_64-linux-gnu-gcc；
– Windows 用户别硬刚，直接用 Docker：docker run --rm -v $(pwd):/src -w /src golang:1.22-alpine go build -o myapp main.go；
• 生产环境交付前，务必用 file myapp 和 ldd myapp（Linux）检查链接类型。
go build 输出文件名和工作目录的关系很绕
新手常困惑：为什么 go build main.go 生成的是 main，而 go build（无参数）却生成一个叫 gobuild 的文件？
本质是 Go 的包发现逻辑：
— go build main.go：只编译这个文件，输出名取自文件名（去掉 .go）；
— go build（无参数）：扫描当前目录所有 .go 文件，找出 main 包，输出名取自当前目录名；
— go build .：等价于无参数，但显式声明“当前模块”，推荐用于模块项目；
— go build ./cmd/myapp：明确指定子命令目录，适合多命令项目（如 CLI 工具含 server 和 cli 两个入口）。
实操建议：
• 交付时永远用 -o 显式指定名称：go build -o bin/app main.go；
• 多文件项目别用 go build *.go，容易漏掉未被 import 的文件（比如配置初始化逻辑在单独 init.go 里）；
• 模块根目录下执行 go build，输出名默认是模块名（go.mod 第一行 module xxx 的最后一段），不是目录名 —— 这点容易被忽略，尤其模块名带斜杠时。
GOOS/GOARCH 一旦设置，go build 就不会校验依赖是否真正支持该平台。某些包在 GOOS=linux 下静默跳过部分逻辑，到运行时才 panic，而且错误信息极难定位。 
