Go环境必须使用1.21+版本，因旧版存在TLS 1.3/HTTP/2支持不全、ALPN协商缺陷及net/http连接复用竞态问题；实操需下载go1.21.13官方包、禁用CGO、配置GOPROXY、排除冲突模块并验证静态链接。
Go 环境必须用 1.21+，低于 1.20 的版本无法安全处理 HTTP/2 和 TLS 1.3 透传
很多团队卡在 Go 1.19 甚至 1.16 上跑网关，结果压测时 http.DefaultTransport 在 TLS 握手阶段频繁超时、httputil.NewSingleHostReverseProxy 转发 WebSocket 失败——根本原因是旧版 crypto/tls 对 ALPN 协商支持不完整，且 net/http 的连接复用逻辑有竞态缺陷。
实操建议：
- Windows 用户直接下载
go1.21.13.windows-amd64.msi（官网镜像站带校验和），别用 Chocolatey 或 Scoop 安装，它们常缓存过期包 - Linux/macOS 执行：
curl -L https://go.dev/dl/go1.21.13.linux-amd64.tar.gz | sudo tar -C /usr/local -xzf -，然后重置GOPATH为$HOME/go，避免与旧项目冲突 -
go env -w GOPROXY=https://goproxy.cn,direct（国内必须设，否则go get github.com/gorilla/mux类依赖会卡死） - 验证：
go version输出应含go1.21.13，且go run -c "package main; import _ 'net/http/httptrace'; func main(){}"不报错
编译时禁用 cgo，否则静态二进制在 Alpine 镜像里 DNS 解析失败
网关部署到 Kubernetes 常用 scratch 或 alpine:latest 镜像，但默认开启 cgo 会让 Go 编译器链接系统 libc 的 getaddrinfo，而 Alpine 用的是 musl libc —— 两者 ABI 不兼容，导致服务启动后所有下游请求返回 lookup user-srv on 10.96.0.10:53: no such host。
正确做法：
立即学习“go语言免费学习笔记（深入）”；
- 编译命令必须加
CGO_ENABLED=0：CGO_ENABLED=0 go build -ldflags="-s -w" -o gateway ./cmd/gateway -
-ldflags="-s -w"删除调试符号和 DWARF 信息，二进制体积减少 40%，启动更快 - 若真需 cgo（比如调用 OpenSSL C API），改用
golang:1.21-alpine基础镜像，并显式apk add ca-certificates - 检查是否生效：
file gateway输出应含statically linked，而非dynamically linked
go.mod 里 exclude 冗余模块，避免 vendor 污染和构建冲突
用 gin 或 chi 做路由层时，其间接依赖常引入 golang.org/x/net 多个版本，而 httputil.NewSingleHostReverseProxy 又强依赖标准库的 net/http 行为。版本错位会导致 Director 函数里 req.URL.EscapedPath() 返回空字符串，路径透传失效。
解决方案：
- 在
go.mod底部加：exclude golang.org/x/net v0.14.0（以实际冲突版本为准） - 运行
go mod graph | grep net查看哪些包拉了x/net，针对性 exclude - 不要用
go mod vendor全量复制——网关类项目 vendor 后体积暴涨且易引入不兼容 patch - CI 构建时加
go mod verify校验，防止有人绕过 exclude 提交脏依赖
交叉编译要指定 GOOS/GOARCH，但 Windows 下不能直接编译 Linux 二进制
本地开发机是 Windows，想直接 set GOOS=linux && set GOARCH=amd64 && go build？不行。Windows 的 go build 默认用 Windows syscall，即使设了 GOOS，仍可能残留 syscall.Syscall 调用，导致 Linux 上 panic： fork/exec /proc/self/exe: operation not supported。
安全方式只有两种：
- 用 WSL2：在 Ubuntu 子系统里执行
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o gateway-linux ./cmd/gateway - 用 Docker 构建容器：
docker run --rm -v $(pwd):/workspace -w /workspace golang:1.21-alpine sh -c "CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o gateway-linux ./cmd/gateway" - Mac 用户可直接用终端执行，但注意
GOARM仅对 ARM 生效，x86_64 无需设 - 生成的
gateway-linux必须用readelf -a gateway-linux | grep INTERP确认解释器路径为/lib/ld-musl-x86_64.so.1（Alpine）或为空（scratch）
