Go规定一个构建单元只能有一个main包，因需唯一入口点；多main报错是设计使然。推荐用cmd/子目录隔离各main包，或用//go:build标签单目录内条件编译。
为什么直接放多个 package main 文件会报 build: multiple main packages
Go 构建器扫描整个目录（或指定路径）下所有 .go 文件，只要发现两个及以上文件声明了 package main 且含 func main()，就立刻终止构建。这不是 bug，而是 Go 的硬性约定：一个构建单元（go build 命令作用域）只能产出一个可执行文件，因此必须有且仅有一个入口点。
常见踩坑场景：
- 把
main.go、cli.go、worker.go全放在同一目录，都写package main - 用
go run .运行当前目录，却忘了其中混着测试用的临时debug.go（也带package main） - IDE 自动生成的
main_test.go被误命名为main.go，但内容其实是测试逻辑
用 cmd/ 目录 + 子目录隔离多个 main 包
这是官方推荐、最干净的做法：每个子命令或服务独占一个子目录，各自是独立的 package main，互不干扰。
目录结构示例：
myapp/
├── go.mod
├── cmd/
│ ├── api/
│ │ └── main.go // package main, func main() { ... }
│ ├── cli/
│ │ └── main.go // package main, func main() { ... }
│ └── migrate/
│ └── main.go // package main, func main() { ... }
└── internal/
└── config/
└── load.go // package config, 可被所有 cmd 复用
构建方式：
go build -o ./bin/api ./cmd/apigo build -o ./bin/cli ./cmd/cligo run ./cmd/migrate --dry-run
关键点：
- 每个
./cmd/xxx是独立构建单元，Go 不会跨目录扫描 -
internal/下的包可被所有cmd/子目录 import，共享配置、日志、DB 初始化等逻辑 - 部署时生成多个二进制文件，粒度清晰，权限/启动方式可分别控制
用构建约束（//go:build）在单个目录内切换 main
适合轻量 CLI 工具，想打包成单个二进制但支持多子命令（如 mytool serve / mytool migrate），又不想拆目录。
AI 舌诊面诊问诊医疗系统 + 诊疗商城系统源码是一套结合 AI 辅助诊断与商品转化的健康类程序，基于浩创云、ThinkPHP（PHP）开发，支持微信服务号与 H5 端，适合做中医舌诊面诊问答、健康建议推送以及配套诊疗商品的运营。
做法是：只保留一个 main.go 作为调度入口，其他“子入口”抽成普通包，用构建标签控制编译哪一组逻辑：
// main.go
package main
import (
"os"
"myapp/cmd/serve"
"myapp/cmd/migrate"
)
func main() {
if len(os.Args) < 2 {
panic("usage: mytool [serve|migrate]")
}
switch os.Args[1] {
case "serve":
serve.Main()
case "migrate":
migrate.Main()
}
}
然后在 cmd/serve/main.go 里写：
//go:build serve
package serve
import "fmt"
func Main() {
fmt.Println("starting server...")
}
构建时加 -tags 指定启用哪个：
go build -tags serve -o mytool-serve .go build -tags migrate -o mytool-migrate .
注意：
-
//go:build注释必须紧贴文件顶部，前面不能有空行或注释 - 不能同时启用多个冲突的构建标签（比如两个文件都标
//go:build serve且没做互斥），否则仍会报 multiple main - 这种方式生成的是多个独立二进制，不是单个二进制里动态 dispatch —— 那属于应用层逻辑，和构建无关
go build 显式指定文件列表的适用边界
仅限临时调试或极小脚本项目。例如你有 main.go（主逻辑）和 debug_db.go（临时 DB 连接测试），两者都是 package main，但你只想编译主程序：
- ✅ 正确：
go build main.go—— 只读这个文件，忽略同目录其他main - ✅ 正确：
go build main.go helper.go—— 显式列出，helper.go 是package main但无func main()，合法 - ❌ 错误：
go build *.go—— shell 展开后可能包含多个main文件，触发报错 - ❌ 错误：
go build .—— 扫描整个目录，撞上多个main就失败
这种写法无法规模化：一旦文件数增加、团队协作或 CI 流水线介入，显式列表极易遗漏或出错，应尽快迁移到 cmd/ 或构建约束方案。
真正容易被忽略的是构建约束的匹配逻辑——它不看文件名、不看目录层级，只认 //go:build 行和 -tags 参数是否精确匹配。哪怕只是多了一个空格或大小写错误，对应文件就会被静默排除，导致 no buildable Go source files，而你可能还在反复检查 package main 写对没。
