go.mod和go.sum必须提交到Git，二者共同锁死依赖版本与校验和，缺一不可；忽略任一文件将导致跨平台构建不一致、checksum mismatch或undefined symbol等错误。
go.mod 和 go.sum 必须提交到 Git
不提交 go.mod 和 go.sum，跨平台构建就等于没锁依赖。Windows 上 go mod tidy 拉的 github.com/some/lib v1.2.3，Linux 上可能拉 v1.2.4 或更旧的 commit——尤其当本地 GOPATH 里残留旧版本时，go list -m all 输出会漂移。
常见错误现象：go build 在 macOS 成功，CI（Linux）报 undefined: somefunc；或本地能跑，Docker 构建失败，提示 checksum mismatch。
-
go.mod记录的是模块路径和最小版本要求，go.sum才是每个依赖确切的 SHA256 校验和，二者缺一不可 -
.gitignore中必须排除bin/、pkg/、*.exe，但坚决保留go.mod和go.sum - 初始化项目第一件事：运行
go mod init example.com/myapp（域名不重要，但不能用本地路径如C: oo或/home/user） - 已有项目补模块：先
go mod init，再go mod tidy，最后检查go.sum是否生成完整（行数应 > 0，且含所有直接/间接依赖）
replace 只用于开发，上线前必须删除
多模块本地联调时，replace 是绕过远程下载的临时方案，但它不是跨平台兼容的“依赖声明”，而是构建时的路径重写规则。它只对当前模块生效，不传递给下游，也不参与 go mod verify 校验。
常见错误现象：CI 构建失败，报 module github.com/yourorg/lib not found；或本地能跑，打包镜像后 panic，提示 cannot load github.com/yourorg/lib。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 正确写法：
replace github.com/yourorg/lib => ./lib，其中./lib必须是合法模块目录（含自己的go.mod，且module声明与 replace 左侧完全一致） - 验证是否生效：
go list -m all | grep yourorg/lib，输出应带=> ./lib - 上线前务必执行
go mod edit -dropreplace=github.com/yourorg/lib，或手动删掉go.mod中对应行 - CI 环境建议加
GOFLAGS="-mod=readonly"，提前暴露未清理的replace
CGO_ENABLED=0 不是可选开关，而是跨平台静态链接前提
默认 CGO_ENABLED=1 会让 Go 编译器尝试链接目标平台的 C 运行时（如 Linux 的 glibc、Windows 的 msvcrt.dll），而宿主机几乎不可能装齐所有平台的 C 头文件和工具链。结果就是：Mac 上交叉编译 Linux 二进制，运行时报 undefined symbol: __cxa_thread_atexit_impl——这不是架构错，是动态链接失败。
常见错误现象：GOOS=linux GOARCH=amd64 go build 成功，但部署到 Alpine 容器后报 no such file or directory；或 Windows 上生成的 .exe 双击无反应，查日志发现缺失 DLL。
- 纯 Go 项目（没
// #cgo、没导入"C"、没调用net.LookupHost等隐式依赖 libc 的函数）——一律设CGO_ENABLED=0 - 命令写全：
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o app-linux main.go - 若必须用 cgo 依赖（如 SQLite、某些 crypto 库），放弃本地交叉编译，改用
docker build或专用工具（如xgo） -
CGO_ENABLED=0后会禁用部分功能（如os/user、net的某些 DNS 解析方式），需确认业务是否受影响
filepath.Join 是路径拼接唯一安全方式
硬编码 "config/" + env + ".yaml" 或 "C:\data\input.txt" 在跨平台构建时不报错，但运行时在非目标平台直接 panic。Go 不会在编译期检查路径分隔符，而 os.Open、http.Dir、embed.FS 等 API 对路径格式敏感。
常见错误现象：Windows 开发者提交的代码在 Linux CI 上 os.Open("C:\config.yaml") panic；或嵌入资源时用 fs.ReadFile(fsys, "ac.txt") 返回 no such file。
- 一律用
filepath.Join("config", env+".yaml")—— 它自动适配/（Linux/macOS）和（Windows） - 读取 embed.FS 资源时，键必须是 POSIX 风格（正斜杠），所以要用
fs.ReadFile(fsys, filepath.ToSlash(path)) -
filepath.FromSlash("a/b/c")可将 POSIX 路径转成本地格式，适合传给os.Open等系统调用 - 避免在日志、配置、HTTP 路由中混用硬编码路径，统一走
filepath或path包
GOOS/GOARCH 设错只是表象，go.mod 不锁、replace 残留、路径拼错、CGO_ENABLED 忘关——这些才是让程序在另一台机器上突然崩溃的根源。 
