go install ./cmd/ 是大型多命令项目构建的正确起点，因 go build ./ 仅扫描一级子目录、跳过 cmd/serve 等嵌套结构，且污染源码树；而 go install ./cmd/... 可递归安装所有合法 main 包，要求 go.mod 中 module 声明合规且包为 package main。
go install ./cmd/ 是大型项目构建的起点，不是 go build ./
大型项目通常有多个命令入口（如 cmd/serve、cmd/migrate、cmd/cli），用 go build ./ 会误触「当前目录一级子包」规则：它只扫描根目录下的直接子目录，跳过 cmd/serve/main.go 这类嵌套结构；更糟的是，它会在每个匹配包目录里生成二进制（比如在 ./cmd/serve/ 下产出 serve 文件），污染源码树。
正确做法是明确指定目标路径：
-
go install ./cmd/serve—— 安装到$GOBIN，要求go.mod中module声明合法（如example.com/myapp），且该包为package main -
go install ./cmd/...—— 递归安装所有cmd/*下的 main 包（Go 1.19+ 支持） - 若报错
no Go files in ...，说明某个cmd/foo/下没有main.go或包声明不是package main
跨平台构建必须显式控制 GOOS/GOARCH 和 -ldflags 注入点
交叉编译时，GOOS=windows GOARCH=amd64 go build 看似简单，但两个坑常被忽略：
-
-ldflags="-X main.version=1.0.0"中的main.version必须指向实际存在的变量——如果版本变量定义在internal/version/version.go且未被main包 import，链接不会报错，但运行时version仍是空字符串 - Windows 目标下输出文件自动带
.exe后缀；Linux/macOS 则无。硬编码-o myapp.exe在非 Windows 平台会生成名字错误的文件 - 建议统一用
-o "myapp$(go env GOEXE)"或在 Makefile 中按平台判断后缀
Makefile 封装构建时，别写死路径，用 go list 动态发现 cmd 包
手动维护 go install ./cmd/serve ./cmd/migrate 很容易漏加新命令。用 go list 自动探测更可靠：
立即学习“go语言免费学习笔记（深入）”；
-
go list -f '{{.ImportPath}}' ./cmd/...能列出所有可安装的 main 包路径（如example.com/myapp/cmd/serve） - 在 Makefile 中组合成一行：
go install $$(go list -f '{{.ImportPath}}' ./cmd/...) - 注意：必须用
$$转义，否则 shell 会提前展开$() - 配合
-ldflags时，建议提取为变量，避免重复拼接
模块路径不合法会导致 go install 静默失败或报 cannot install non-main package
go install 对模块路径敏感——它不是纯构建命令，而是「安装」动作，依赖模块元信息做合法性校验。常见问题：
-
go.mod中module值为空、为.或含非法字符（如空格、大写字母开头），go install ./cmd/serve会报cannot install non-main package，即使代码完全正确 - 本地开发时用
go mod init local/myapp初始化没问题，但发布前应改为语义清晰的域名路径（如github.com/owner/myapp） - Go 1.21+ 默认关闭 GOPATH 模式，
$GOBIN必须在$PATH中才能直接调用安装后的命令，这点容易被忽略
真正卡住人的从来不是语法，而是 go.mod 的 module 声明是否合规、-X 引用的包路径是否和 import 一致、以及 go list 输出是否真包含你认为该有的包——这些细节不验证，构建流程再自动化也白搭。
