编译卡死在go mod download或go build阶段，是因GOSUMDB默认回源sum.golang.org校验超时；必须显式设置GOSUMDB=off（仅配GOPROXY无效），vendor需配合-mod=vendor参数启用，且CGO_ENABLED=0可规避交叉编译工具链缺失问题。
编译卡死在 go mod download 或 go build 阶段
这不是网络慢，而是模块校验机制在尝试连接 sum.golang.org 时超时阻塞。嵌入式定制系统通常无外网或 DNS 不通，但 Go 默认仍会回源验证校验和，导致整个构建流程挂起。
-
GOSUMDB=off必须显式设置，仅设GOPROXY不够；国内镜像如https://goproxy.cn只代理模块下载，不代理校验和服务 - 执行
go env -w GOSUMDB=off后，再运行go mod download，卡住现象立刻消失 - 若系统已禁用所有外网访问（包括 proxy.golang.org），
GOPROXY=direct是唯一安全选项，此时GOSUMDB=off更不可省略
vendor 目录存在但 go build 仍报 cannot find module
说明 vendor 未被激活，Go 仍试图联网解析模块路径。vendor 不是“打包即生效”，它依赖 -mod=vendor 显式启用，且要求 go.mod 和 vendor/modules.txt 完全匹配。
- 确认
vendor/modules.txt存在且内容非空；缺失该文件会导致 vendor 机制静默失效 - 编译时必须加
-mod=vendor参数：go build -mod=vendor -o app ./cmd/app - 不要混用
go mod vendor和go mod tidy：后者可能更新go.mod导致modules.txt过期，触发回源
交叉编译时因 CGO_ENABLED=1 导致构建中断
嵌入式定制系统往往没有 aarch64-linux-gnu-gcc 或缺失 sysroot，而 CGO 启用后，go build 会尝试调用 C 工具链，直接报错 exec: "aarch64-linux-gnu-gcc": executable file not found。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 先检查是否真需要 cgo：用了
os/user、net、os/exec等包才会触发；纯 HTTP 服务、JSON 解析等场景可关掉 - 强制关闭：
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o app ./cmd/app - 若必须用 cgo（如驱动封装），则需提前部署交叉工具链，并通过
CC_aarch64_linux_gnu=aarch64-linux-gnu-gcc指定编译器
私有模块或本地 SDK 编译失败
嵌入式定制系统常含内部 SDK 或离线模块，go mod download 无法拉取，但 replace 配置没生效，导致构建找不到包。
立即学习“go语言免费学习笔记（深入）”；
-
replace必须写在go.mod顶层，不能放在子模块的go.mod中 - 路径要绝对或相对于项目根目录，例如：
replace internal/sdk => /opt/embedded-sdk - 执行
go mod edit -replace后，务必运行go mod tidy更新go.sum（即使GOSUMDB=off，也要生成占位记录） - 验证是否生效：
go list -m all | grep sdk应输出本地路径，而非原始模块名
GOSUMDB 到 GOPROXY，再到 -mod=vendor 和 replace 路径，最后还要确保 CGO_ENABLED=0 不被任何依赖悄悄绕过——漏掉任意一环，都可能让编译卡在某个你想不到的地方。 
