build tags 是 go 中控制文件参与编译的元指令，必须置于文件顶部、package 前且无空行；支持 //go:build（推荐）和兼容的 // +build，多条件用空格（与）或逗号（或），可实现平台适配、功能开关及 vendor 兼容。
Build Tags 是什么，为什么不能写在代码里
Go 的 //go:build 和 // +build 不是注释，而是编译器识别的元指令。它们必须出现在文件顶部、任何 package 声明之前，且中间不能有空行——否则整个 tag 就失效。
常见错误：把 //go:build linux 写在 package main 后面，或夹在 import 和 package 之间；结果 build 时完全不生效，还查不出原因。
- 只支持特定语法：
//go:build linux或//go:build !windows，不支持&&||连写（得用空格或逗号） -
// +build是旧写法，已弃用但仍兼容；新项目统一用//go:build，且必须配对使用// +build（Go 1.17+ 要求双写以兼容老工具链） - 多个条件用空格分隔：
//go:build linux darwin表示“linux 且 darwin”，想表达“或”得用逗号：//go:build linux,darwin
如何让不同平台加载不同实现文件
典型场景：为 Windows 和 Unix 分别提供 exec.Command 的封装，避免跨平台编译失败。关键不是改逻辑，而是控制哪些文件参与编译。
比如目录下有：
立即学习“go语言免费学习笔记（深入）”；
cmd.go cmd_linux.go cmd_windows.go
其中 cmd_linux.go 顶部写：
//go:build linux
// +build linux
package main
func runShell() { ... }
cmd_windows.go 顶部写：
//go:build windows
// +build windows
package main
func runShell() { ... }
这样 go build 在 Linux 下只会编译 cmd.go 和 cmd_linux.go，Windows 下自动跳过 cmd_linux.go。
- 所有同包文件必须声明相同
package名，否则报found packages main and main - 不能靠文件名判断平台，必须显式加 tag；否则
go build会尝试编译所有文件，导致重复定义或 syscall 冲突 - 如果某文件没加任何 tag，默认参与所有构建——这点常被忽略，导致 Windows 上意外编译了含
unix.Syscall的代码
用自定义 Build Tag 控制功能开关
比如你想在调试版开启日志采样，在发布版关闭，又不想改代码逻辑——用自定义 tag 最干净。
写一个 debug.go：
//go:build debug // +build debug package main const DebugMode = true
再写一个 release.go：
//go:build !debug // +build !debug package main const DebugMode = false
然后构建时指定：go build -tags debug 或 go build -tags ''（空 tag 表示不启用任何自定义 tag）。
-
-tags参数值是空格分隔的字符串列表，go build -tags "debug sqlite"表示同时启用两个 tag - 注意 shell 转义：Linux/macOS 下带空格的 tag 要引起来；Windows cmd 中引号行为不同，建议统一用单引号或避免空格
- 自定义 tag 不受平台限制，但一旦用了，就必须确保所有环境都提供对应文件，否则可能因缺少
DebugMode定义而编译失败
Build Tags 和 go.mod / vendor 的关系
Build Tags 只影响编译阶段的文件筛选，和模块依赖无关。但有个关键点：vendor 目录里的代码，其 Build Tags 是否生效，取决于你构建时是否启用了 -mod=vendor，以及 vendor 里文件本身是否写了正确 tag。
常见坑：你本地开发时用 go build -tags sqlite 没问题，但 CI 里用 go build -mod=vendor -tags sqlite 却报错——大概率是 vendor 里某个依赖的 .go 文件漏写了 tag，或写了错误的 tag（比如只写了 // +build sqlite 没配 //go:build），导致 Go 1.17+ 拒绝识别。
- vendor 不会自动帮你补 tag，它只是静态快照；更新依赖后务必检查 vendor 中相关文件的 build tag 完整性
- 交叉编译时尤其危险：比如在 macOS 上
GOOS=linux go build -tags systemd，若 vendor 里 systemd 相关文件只标了//go:build linux systemd，那没问题；但如果标的是//go:build systemd（缺 linux），就会在 macOS 主机上误参与编译，然后爆undefined: unix.SYS_EPOLL_CREATE1
Build Tags 看似简单，真正难的是保持跨平台、跨环境、跨依赖的一致性——每个文件的 tag 都得像接口契约一样被所有人遵守，少一个空格，就可能让整条 CI 流水线卡住。
