//go:build 是文件级编译门禁，必须紧贴 package 声明前、顶格书写、后跟空格和条件；错误格式或位置会导致文件静默不参与编译，需用 go list -f '{{.GoFiles}}' 验证。
//go:build 标签不是“开关”，而是文件级编译门禁——写错位置、格式不对、漏掉空行，对应文件就彻底不进编译流程，连语法错误都不会报。
build tags 写在哪儿才生效
必须紧贴 package 声明前，前面最多一个空行，不能缩进，不能换行，后面必须跟一个空格再写条件。
常见错误现象：go build 成功但功能没出现；go list -f '{{.GoFiles}}' ./ 输出里根本看不到你写的 _linux.go 文件。
-
//go:build linux✅ 正确（顶格、空格后接条件） -
//go:build (linux)❌ 静默失效（括号非法） -
//go:build linux,arm64❌ 失效（逗号分隔不被支持，要用&&） -
//go:build linux && arm64✅ 正确 - 写在
package main后面、函数里、中间注释中 → 全部忽略
Linux 和 Windows 实现必须拆文件，不能塞 if runtime.GOOS
运行时判断 runtime.GOOS == "windows" 只控制执行路径，但 Windows 专属的 import "syscall" 或 import "C" 在 Linux 编译时会直接报错——因为 Go 编译器要解析所有 import，不管是否执行。
典型场景：设置终端标题、调用系统锁、读取注册表、访问 Unix socket。
立即学习“go语言免费学习笔记（深入）”；
- 建
title_windows.go，开头写//go:build windows，里面调kernel32.dll - 建
title_linux.go，开头写//go:build linux，里面用unix.IoctlSetInt - 公共入口
title.go定义接口和NewTitleSetter()工厂函数 - 绝不要在同一个文件里写
if runtime.GOOS == "windows" { ... }+ cgo 代码
交叉编译时 -tags 必须显式传，GOOS 不自动生效
GOOS=linux go build 不会让 //go:build linux 文件自动参与编译——它只影响标准库的构建行为。你的自定义标签仍需手动加 -tags linux，否则那些平台专属逻辑压根没编译进去。
CI 中常见坑：本地 GOOS=linux go build 能跑，CI 脚本却漏了 -tags linux，结果二进制在目标机器上 panic。
- 验证是否真包含：用
go list -f '{{.GoFiles}}' -tags linux ./ - 测试平台逻辑：用
go test -tags linux ./，而不是GOOS=linux go test - CI 脚本里避免引号陷阱：
go build -tags "linux cgo"正确，go build -tags="linux cgo"会被 shell 拆成两个参数，go只收到linux
如何验证 build tags 是否真正起作用
最可靠的验证方式不是看编译是否成功，而是确认目标文件是否真的被选中参与构建。
容易被忽略的一点是：go build 默认不检查带 tag 的文件是否满足条件，它只把不匹配的文件整个跳过——这意味着你改了 //go:build 但忘了清理缓存，或者写了两行冲突的标签（比如同时存在 //go:build linux 和 //go:build windows），go list 就会显示空列表，而你可能还以为是代码逻辑问题。
- 每次改 tag 后，先跑
go list -f '{{.GoFiles}}' -tags your_tag ./ - 确保没有同时存在
//go:build和旧式// +build（Go 1.17+ 只认前者） - 如果要兼容老版本 Go，可并列写两行：
//go:build linux紧接// +build linux，中间无空行
