构建标签与条件编译

构建标签（build constraint，旧称 build tag）决定一个文件在什么条件下参与编译，用于平台差异隔离、按需启用集成测试、以及排除示例文件。以下规则以 go help buildconstraint（go1.27.0）为准，标注处经实测。

1. 语法

约束是一条以 //go:build 开头的行注释：

//go:build linux || (darwin && cgo)

package mypackage

规则要点（help 原文归纳）：

• 可以出现在任意源码文件顶部，但前面只能有空行和其他注释——Go 文件里必须在 package 子句之前。
• 约束行后面应当跟一个空行，否则会与包文档注释混在一起（package doc 被污染）。
• 表达式由 build tag 经 &&、||、! 和括号组合；一个文件出现多条 //go:build 行是错误。
• 旧语法 // +build（Go 1.16 及之前使用，help 原文明确此版本线）逗号表示 AND、多行表示 OR；gofmt 遇到旧语法会自动补写等价的 //go:build 行。

两种格式共存时 //go:build 行生效、// +build 被忽略（实测：同时写 //go:build linux 与 // +build windows 的文件在 windows/amd64 下被排除，报 build constraints exclude all Go files，旧行未参与决策）。新代码只写 //go:build；需要兼容旧工具链时靠 gofmt 同步维护两行。

//go:generate、//go:embed、//go:build 都长得像，但只有 //go:build 是构建约束——前两者是工具指令，由 go generate 与编译器在别处处理，别指望 //go:embed 能开关文件。

2. 哪些 tag 会被满足

某次构建中自动满足的 tag（help 原文）：

• 目标 GOOS（linux/windows/darwin…）与 GOARCH（amd64/arm64/386…）；
• 架构特性 tag，如 amd64.v2（GOAMD64=v2 时连 amd64.v1 一起满足，向下取反请用 //go:build !amd64.v2）；
• unix（GOOS 为 Unix 系时）、编译器名 gc/gccgo、cgo（CGO_ENABLED 可用时）；
• 每个 Go 大版本一个 tag：当前 1.27 工具链下 go1.1 到 go1.27 全部满足；minor/补丁版本没有 tag（go1.27.1 这种写法不存在）；
• -tags 传入的自定义 tag。

另外两条行为（help 原文）：GOOS=android 同时匹配 linux 的 tag 与文件名规则；ios 同理匹配 darwin。

模块 go 版本 ≥ 1.21 时，若约束里有 go1.x 项，该文件的语言版本会被降级到 x（help 末段）——即 //go:build go1.20 的文件里不能用 1.21+ 的新语法，哪怕工具链是 1.27。

文件名隐式约束

file_linux.go         // 只在 Linux 编译
file_amd64.go         // 只在 amd64 编译
file_linux_amd64.go   // Linux + amd64

命名匹配 *_GOOS、*_GOARCH、*_GOOS_GOARCH 的文件自动带上对应约束，与显式 //go:build 求交集：xxx_windows.go 里再写 //go:build linux，结果永远不编译。纯约定俗成的 purego tag 用于汇编替代的纯 Go 实现（help 点名此惯例），它不是 cgo 的反义词，控制"要不要 cgo"用 //go:build cgo / !cgo。

全排除

//go:build ignore

排除任意文件的惯例写法（示例文件、手工脚本），其他无意义词也能达到效果，但约定用 ignore。

3. 自定义标签

go build -tags debug
go test -tags "integration,debug"   # 逗号分隔
GOFLAGS="-tags=integration" go build ./...  # 环境变量，实测等价

成对文件的正确写法是互补约束（旧版本文档这里写"无标签的生产文件"，那样两个文件在带 tag 构建时会重复定义，是错的）：

// msg_off.go
//go:build !integration

package main

const Msg = "integration OFF"

// msg_on.go
//go:build integration

package main

const Msg = "integration ON"

实测（go1.27，windows/amd64）：

$ go run .
Msg = integration OFF
$ go run -tags integration .
Msg = integration ON
$ GOFLAGS="-tags=integration" go run .
Msg = integration ON

4. 实战应用

平台差异隔离

// file_linux.go
//go:build linux

package platform

const Newline = "\n"

// file_windows.go
//go:build windows

package platform

const Newline = "\r\n"

跨平台代码建议同时提供兜底文件（//go:build !linux && !windows），避免支持列表外的 GOOS 编译时缺符号。

隔离慢测试

// integration_test.go
//go:build integration

package mypackage_test

CI 默认 go test ./... 不带该 tag，本地需要时用 -tags integration 显式跑。

按 Go 版本提供 API

// join_go1_20.go
//go:build go1.20

package mypackage

import "errors"

var ErrJoin = errors.Join

需要兼容旧工具链时写双版本文件；只服务新工具链则不需要——go1.x 项的含义是"当前工具链 ≥ x"，1.27 构建时恒真。

5. 常见陷阱

6. 实战建议

• 能用文件名约定（_linux.go 等）表达的平台差异就别写显式约束，可读性更好；两者都要时记住"求交集"。
• 生产代码少用自定义 tag 做功能开关——它们极易在 CI/IDE/go vet 里漏传导致从未编译；功能开关走构建变量注入或配置。
• IDE（gopls）按当前 GOOS/GOARCH/-tags 灰掉的文件不代表错误，跨平台提交前至少 GOOS=linux GOARCH=arm64 go build ./... 冒烟一次。
• 检查约束是否解析正确，最可靠的是直接 go build ./... 或 go list -f '{{.GoFiles}}' 看文件归属，而不是肉眼数空行。