Go构建要求每个可执行程序有且仅有一个main包和main函数；多main包需用显式文件指定、构建约束或拆分独立main包解决，核心是遵守“一个目录一个包、一个程序一个入口”约定。
多个 main 包文件导致 build: multiple main packages
Go 不允许一个构建单元里存在多个 main 函数，更不允许多个 package main 文件被同时纳入同一 go build 命令。这不是限制，而是 Go 构建模型的底层约定：每个可执行程序必须有且仅有一个入口点。
常见错误现象是把多个带 package main 的 .go 文件（比如 main.go、cli.go、server.go）放在同一目录下，然后直接 go build —— 此时 Go 会扫描全部 .go 文件，发现不止一个 main 函数，报错 build: multiple main packages。
- 解决方法不是删文件，而是控制哪些文件参与构建
- 用
go build <file1> <file2>显式指定要编译的文件（例如go build main.go server.go），其余同目录下的main文件会被忽略 - 或用
//go:build构建约束注释 +go build -tags分离不同入口，适合 CLI 工具多命令场景（如mytool serve和mytool migrate） - 注意：不能靠文件名区分，Go 只看
package main和func main()，哪怕叫xxx_test.go，只要包是main且含main()，就参与构建
go build -o 指定输出路径但生成了空文件或报错 no buildable Go source files
这个错误说明 Go 找不到符合当前构建条件的 package main 文件。根本原因常是构建约束不匹配，或者路径没指对源码位置。
典型场景是你在项目根目录执行 go build -o ./bin/app ./cmd/server，但 ./cmd/server 下没有 package main，或只有 package server；又或者该目录下所有 .go 文件都加了 //go:build !dev，而你没传 -tags dev。
立即学习“go语言免费学习笔记（深入）”；
- 先确认目标目录下确实有
package main且至少一个文件不含冲突的//go:build条件 -
go build -o后面的路径是输出路径，不是输入路径；输入路径写在最后（如go build -o bin/app cmd/server） - 如果目标是单个文件，必须显式列出：
go build -o bin/cli main.go cli.go，不能只写目录 - Windows 下注意反斜杠和路径分隔符，统一用正斜杠或双反斜杠，
go build对路径格式敏感
想共用 main 包逻辑但避免冲突：用子命令还是拆成独立 main 包？
当你要支持 app serve、app migrate、app version 这类子命令时，核心矛盾在于：复用初始化逻辑（配置加载、日志设置等） vs. Go 要求每个可执行文件只能有一个 main。
两种主流做法，区别不在“能不能”，而在维护成本和部署粒度：
- 单
main包 + 子命令分发：所有逻辑在同一个package main里，用flag或spf13/cobra解析子命令，共享全局 setup。最简单，二进制只有一个，但每次更新全量覆盖 - 多个独立
main包：每个子命令一个目录（如cmd/serve、cmd/migrate），各自package main，通过import "yourproject/internal/xxx"复用非 main 层代码。构建时分别执行go build -o bin/app-serve ./cmd/serve等。部署灵活，但需管理多个二进制 - 别试图用
init()或变量导出绕过main限制——Go 不允许跨main包调用函数，main包的符号对外不可见
为什么 go run 能跑单个 main.go 却不报错，而 go build 就不行？
go run 默认只编译并运行你明确列出的文件（如 go run main.go），它不会自动扫描同目录其他 .go 文件。而 go build 默认行为是“构建当前目录下所有可构建的 Go 文件”，包括那些你忘了注释掉的测试入口或临时调试用的 main.go.bak。
-
go run是开发快捷键，go build是发布动作，设计目标不同 - 如果你在目录里放了
main.go和debug_main.go（也含func main()），go run main.go没事，但go build会失败 - 安全做法：给非主入口文件加上构建约束，比如在
debug_main.go顶部加//go:build ignore，这样go build默认跳过它 - 也可以用
go build -o app .中的.表示当前目录，但前提是目录下**只应存在一个**main包文件；否则就得老老实实列文件名
事情说清了就结束。关键不是语法多难，而是 Go 构建系统从不隐藏它的假设：一个目录 = 一个包，一个可执行程序 = 一个 main 包 + 一个 main() 函数。所有问题，基本都出在试图打破这个假设，又没补上对应约束。
