Go 构建约束（build constraints）的用法

meiki meiki 更新于
📁 Technology
Go

写跨平台的 Go 代码时早晚会碰到一个问题：同一个功能在 Linux 和 Windows 上实现完全不同，但又想让 go build 在每个平台上只编译对应的那份。这就是构建约束（build constraints，也叫 build tag）干的事——编译器按条件决定哪些文件参与编译。

构建约束有两种方式：文件名后缀和 build tag 注释。

文件名后缀

最简单的方式，直接在文件名里带上平台信息，格式是：

filename_GOOS.go
filename_GOARCH.go
filename_GOOS_GOARCH.go

比如 net_linux.go 只在 Linux 下编译，net_windows.go 只在 Windows 下编译。Go 标准库里大量使用这种方式，看一眼 os 包的源码就能看到。

这种方式适合跨平台实现，简单直接，不需要写任何注释。

Build tag 注释

更灵活的方式是在文件顶部写注释标记，可以组合多个条件，也可以用自定义 tag。

新语法（Go 1.17+）

//go:build linux && amd64

注意 // 和 go 之间没有空格，这和普通注释不一样。

用标准的布尔运算符组合条件：

//go:build linux || darwin
//go:build !windows
//go:build (linux || darwin) && amd64

旧语法（Go 1.16 及之前）

// +build linux,386

旧语法用逗号表示 AND，空格表示 OR，多个条件可以写多行（多行之间是 AND 关系）。这套规则很反直觉，容易写错：

// +build linux,386 darwin,!cgo

上面这行的意思是 (linux AND 386) OR (darwin AND NOT cgo)，不看文档很难一眼看懂。

Go 1.17 之后，gofmt 会自动在旧语法下面补一行新语法，保持兼容：

//go:build !windows && !plan9
// +build !windows,!plan9

Go 1.18 开始，go fix 工具会直接移除旧的 // +build 注释。现在写新代码直接用 //go:build 就行。

写法要求

build tag 必须放在文件最顶部，在 package 声明之前，和下面的代码之间要有一个空行：

//go:build linux

package main

少了那个空行，Go 编译器不会把它识别为构建约束，而是当成一句普通注释——文件照常参与所有平台的编译，且不会有任何报错，这种坑最难查。

自定义 tag

除了平台和架构，还可以定义自己的 tag，在编译时通过 -tags 传入：

//go:build use_feature

编译时：

go build -tags use_feature

不带 -tags use_feature 时这个文件会被忽略，带了才参与编译。多个 tag 用空格分隔：

go build -tags "feature1 feature2"

这个用法常见于功能开关、调试模式、或者区分 CE/EE 版本之类的场景。

tag 可以用的值

  • 操作系统：linux、darwin、windows 等（对应 GOOS）
  • 架构：amd64、arm64、386 等（对应 GOARCH）
  • 编译器：gc、gccgo
  • CGO：cgo
  • Go 版本：go1.21、go1.22 等
  • 自定义：任意字符串，通过 -tags 传入
  • ignore：约定俗成的忽略标记，让文件永远不参与编译

几个容易踩的坑

这套机制最坑的地方在于：配错了基本不报错，文件要么被静默忽略，要么被静默全平台编译，全靠你自己发现。几个我踩过或见人踩过的：

  • macOS 的 GOOS 是 darwin，不是 macos/osx。文件名后缀只认 Go 已知的 GOOS/GOARCH 词。utils_macos.go 里的 macos 不是合法 GOOS，于是它不构成任何约束，会在所有平台都编译——你以为它只在 Mac 上跑，其实哪都跑。要限定 macOS 得写 utils_darwin.go。

  • _ 或 . 开头的文件会被直接忽略。这是另一套独立机制：go build 默认跳过文件名以 _ 或 . 开头的文件（_test.go 这种 _xxx 后缀除外）。临时想排除一个文件，重命名成 _foo.go 比加 tag 还快。

  • 后缀约束对测试文件一样生效。foo_linux_test.go 既是测试文件，又被约束到只在 Linux 下编译，跨平台跑 go test 时要留意。

  • 拿不准就让 go 工具告诉你。与其盯着文件名猜，不如直接看当前条件下哪些文件会被编译：

    go list -f '{{.GoFiles}}'
GOOS=windows go list -f '{{.GoFiles}}'

    切换 GOOS/GOARCH/-tags 再跑一遍，列表的变化一目了然，比肉眼读约束可靠得多。

小结

两种方式各有适用场景：纯粹按平台/架构分实现，用文件名后缀最干净；要组合条件、做功能开关、区分版本，用 //go:build 注释。新代码统一上新语法，旧的交给 gofmt/go fix 自动迁移。

真正要记牢的是那条隐患——构建约束写错了通常不会报错。所以养成习惯：改完约束顺手用 go list 验一下到底编译了哪些文件，别等到换平台构建出锅才回头找。