go build tags 是文件级编译门禁，非预处理器开关；必须用 //go:build 紧贴 package 前、格式严格，错误则文件被完全忽略，需用 go list -f '{{.gofiles}}' 验证。
Go 没有预处理器，build tags 不是“开关”，而是“文件级编译门禁”——写错或漏配，对应文件就彻底不进编译流程，连语法检查都不会触发。
文件顶部注释格式必须严格对齐
Go 1.17+ 推荐用 //go:build，但它不是普通注释：必须紧贴 package 声明前、不能缩进、不能换行、后面必须跟一个空格再写条件。写成 //go:build linux && cgo 对，写成 //go:build (linux && cgo) 或 //go:build linux, cgo（逗号后多空格）都会静默失效。
常见错误现象：go build 成功但预期逻辑没生效；go list -f '{{.GoFiles}}' ./ 发现带 tag 的文件根本不在输出里。
-
//go:build和// +build不能共存，Go 1.17+ 只认前者 - 如果还要兼容老版本 Go，可同时写两行：
//go:build linux紧接// +build linux，中间无空行 - 所有 build tag 行必须在文件最顶部，前面只能有空白或纯
//注释
多个平台实现必须拆文件，不能塞进 if runtime.GOOS
运行时判断 runtime.GOOS == "linux" 只控制执行路径，但 Linux 专属的 cgo 调用、系统头文件引用、golang.org/x/sys/unix 导入，在 Windows 编译时会直接报错——build tags 才是让这些代码“物理消失”的唯一方式。
典型场景：数据库驱动、信号处理、文件锁、syscall 封装。
Colly 是一个用于 Go 语言的快速开源爬取和爬虫框架。它适用于从简单的页面提取到异步爬虫处理大量页面集合，支持请求回调和结构化解析。
- 建
db_linux.go，开头写//go:build linux，导入github.com/mattn/go-sqlite3 - 建
db_darwin.go，开头写//go:build darwin，导入modernc.org/sqlite - 绝不要在同一个文件里写
if runtime.GOOS == "linux" { ... cgo ... }—— 非 Linux 平台编译直接失败
交叉编译时 -tags 必须显式传，GOOS 不自动生效
GOOS=linux go build 不会自动启用 //go:build linux 文件，它只影响标准库的构建行为；你的自定义标签仍需手动加 -tags linux，否则那些文件被跳过，二进制可能“编译成功但运行崩溃”。
CI 中常见坑：本地 GOOS=linux go build 能跑，CI 脚本却漏了 -tags linux，导致平台专属逻辑完全没编译进去。
- 验证是否真包含：用
go list -f '{{.GoFiles}}' -tags linux ./查看哪些文件被选中 - 测试平台逻辑：用
go test -tags linux ./，而不是GOOS=linux go test - CI 脚本中避免引号陷阱：
go build -tags "linux sqlite"正确，go build -tags="linux sqlite"会被 shell 拆成两个参数，go 只收到linux
测试文件加了 build tags 就默认不跑
go test 默认不启用任何 tag，所以写了 //go:build integration 的测试文件，在 go test ./ 下压根不会被发现——不是失败，是“不存在”。这极易造成覆盖率虚高、线上才暴露问题。
集成测试依赖外部服务、cgo 或特定工具链，不该混入日常单元测试流。
- 运行带 tag 的测试：必须显式
go test -tags integration ./ - 想验证多平台编译通过性：用
GOOS=windows go build -o /dev/null .，不生成二进制，只做类型检查 - 避免在
_test.go文件里混用平台逻辑，应拆为storage_s3_test.go（//go:build s3）和storage_fs_test.go（//go:build !s3）
最容易被忽略的是：build tags 生效与否，完全取决于文件是否进入编译器输入列表，而不是你“以为它该被用上”。一次 go list -f '{{.GoFiles}}' -tags xxx ./ 就能立刻验证，比猜半天快得多。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
