go.mod路径必须用标准域名格式，不能用本地路径；正确做法是统一使用如github.com/yourname/myapp的合法域名风格路径，避免跨平台解析失败。
go.mod 路径必须用标准域名格式，不能用本地路径
直接用 go mod init ./myapp 或 go mod init C:\project\myapp 会埋下跨平台隐患：Windows 下生成的模块路径带反斜杠或盘符，Linux/macOS 解析失败；go build 在不同系统上可能报 module myapp is not a dependency of module 或找不到 import 包。
正确做法是统一使用合法域名风格的模块路径，例如：go mod init github.com/yourname/myapp。这个路径不依赖本地文件系统结构，所有平台都能一致解析。
- 模块路径不要含空格、中文、特殊符号
- 避免与 GOPATH 冲突：建议关闭 GOPATH 模式（
GO111MODULE=on），或干脆不设 GOPATH - 初始化后检查
go.mod文件第一行是否为module github.com/...，不是则手动修正
filepath.Join 替代硬编码路径，连 embed.FS 也要转斜杠
跨平台最常崩在路径拼接上。写 "config/" + env + ".yaml" 在 Windows 上可能变成 configdev.yaml（缺少分隔符），或在 Linux 上被 http.Dir 拒绝——它只认正斜杠。
所有路径操作必须走 path/filepath，包括读取嵌入资源：
- 用
filepath.Join("config", env+".yaml")替代字符串拼接 - 读
embed.FS时，键名必须是 POSIX 风格（/），所以要先调filepath.ToSlash(path)转义，再传给fs.ReadFile(fsys, ...) -
os.OpenFile、ioutil.ReadFile、http.Dir全部适用该规则
replace 指令只在当前模块生效，发布前必须清理
开发多模块项目时，常用 replace github.com/your/lib => ./lib 做本地联调。但这个指令不会透传给下游模块，CI 构建时若没删掉，就会因找不到 ./lib 路径而失败——尤其在 Linux CI 机上，./lib 可能根本不存在或权限不对。
安全做法：
- 本地调试用
replace，但提交前用go mod edit -dropreplace=github.com/your/lib清理 - CI 流水线中加一步
go list -m all | grep '=>'，检测残留 replace - 私有模块别靠 replace，改用
GOPRIVATE=git.company.com/*配置
go.sum 必须随模块提交，且各模块独立维护
一个仓库多个 go.mod（如 service/go.mod 和 shared/go.mod）时，每个模块都要有自己的 go.sum。如果只提交主模块的 go.sum，子模块更新依赖后，其他协作者 go mod tidy 会拉错版本，导致 checksum mismatch 错误。
关键动作：
- 每个含
go.mod的目录都执行一次go mod tidy - 所有
go.sum文件都提交进 Git，不忽略 - CI 构建主模块前，先
cd shared && go mod tidy && cd -，确保子模块干净
go build -trimpath 消除绝对路径影响，GOOS=linux 构建时不加 -buildmode=exe 就出不了可执行文件，这些细节一旦漏掉，就不是“换个系统跑一下”的事了。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
