Go build 标签没有生效如何检查文件命名

文件写了 //go:build featurex，传入 -tags=featurex 后却没有参与构建，先检查完整文件名：probe_windows.go 仍有 Windows 平台限制。显式标签满足，不代表文件名条件也满足。反过来，probe_featurex.go 不会自动获得自定义标签限制，必须写约束注释。

先把构建目标和标签写成明确输入

把候选文件、目标平台和附加标签作为同一份构建输入保存。下面是给读者自行使用的命令示例，不是本文实际执行记录；在目标包目录内运行，或把末尾的点替换成包路径。

# 查看当前有效目标、模块、附加参数及 cgo 配置
go env GOOS GOARCH GOFLAGS GOMOD CGO_ENABLED
# 按包选择文件，显式指定附加标签
go list -tags=featurex -f '{{.GoFiles}}' .

GOOS、GOARCH 指向目标，不一定是当前电脑平台。-tags 补充标签集合，不是交叉编译开关。不要用 -tags=windows 代替 GOOS=windows，人为满足平台词可能混入不适合真实目标的实现。有关目标、标签和命令参数，参见 Go 命令文档：https://pkg.go.dev/cmd/go#hdr-Build_constraints。

文件名和标签是共同约束，不是互相覆盖

在按包构建时，可把选择条件理解为“文件名隐含限制满足，并且显式表达式满足”。probe_linux_amd64.go 约束系统与架构；probe_amd64_linux.go 不是同一种组合，末尾 linux 仍可限制系统，但前面的 amd64 不构成规范的系统加架构后缀。别靠倒序名字表达双重限制。

这些规则涉及“已知平台/架构词”，不是任意下划线单词。另有兼容关系：Android 目标匹配 linux 标签及文件，iOS 匹配 darwin，illumos 匹配 solaris；不要把平台后缀概括成绝无例外的字面相等。命名细节可查看官方文件选择实现：https://go.dev/src/go/build/build.go。

让平台实现与默认实现互补存放

假设只在 Linux 且启用 featurex 时使用专用实现，两个文件应在同一个包目录里提供互补的 Mode 声明。为避免默认文件再被平台后缀收窄，使用普通名称 probe_default.go。以下两个独立文件可放进已有模块中的 probe 包。

probe_linux.go：

//go:build linux && featurex

package probe

// Mode 返回已启用的专用实现名称。
func Mode() string {
    return "linux-featurex"
}

probe_default.go：

//go:build !(linux && featurex)

package probe

// Mode 为不满足专用条件的目标提供默认实现。
func Mode() string {
    return "default"
}

普通 Linux 目标加 featurex 时应选专用文件；不加标签时应选默认文件。Windows 目标即使加 featurex，也应选默认文件。这是代码条件推导的预期，不是已运行的输出。Android 的 linux 兼容规则也会作用于这组表达式；若产品明确排除 Android，需要在专用条件和默认条件中一致加入相反限制。

约束放在文件顶部、package 之前，后面留空行。一个文件只写一条 //go:build，用 &&、||、! 和括号表达组合；不要把多个声明当成叠加条件。旧工具链若仍需 // +build，新旧表达式必须等价，不要手工维护两套不同规则。

从 go list 查询文件归属

源文件目录是存放模型，构建文件列表才是本次查询结果。GoFiles 是选入的普通 Go 源文件；包含 import C 的文件另看 CgoFiles。IgnoredGoFiles 可帮助发现约束排除的文件；TestGoFiles 和 XTestGoFiles 分别涉及包内测试与外部测试包，不能用它们证明普通构建已经包含测试实现。

# 在示例 probe 包目录中比较三个目标条件，命令格式适用于 POSIX shell
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go list -tags=featurex -f '选入={{.GoFiles}} 排除={{.IgnoredGoFiles}}' .
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go list -f '选入={{.GoFiles}} 排除={{.IgnoredGoFiles}}' .
GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go list -tags=featurex -f '选入={{.GoFiles}} 排除={{.IgnoredGoFiles}}' .
# 含 cgo 或测试文件的包，读取更完整的归属信息
go list -tags=featurex -f '普通={{.GoFiles}} cgo={{.CgoFiles}} 包内测试={{.TestGoFiles}} 外部测试={{.XTestGoFiles}} 排除={{.IgnoredGoFiles}}' .

前三条只是这组无 cgo 示例的对照；排查真实依赖 cgo 的包时保留其实际配置，不要照抄关闭设置。若文件以点或下划线开头，可能根本不进入 IgnoredGoFiles，列表中缺失不等于标签注释有问题。若包加载报错，先处理报错，不把空列表当成成功证据。结构字段说明见 https://pkg.go.dev/go/build#Package。

标签仍不符合预期时检查命令入口

同一份代码，go build . 与 go build probe_linux.go 不能作为相同的筛选实验。显式列出 .go 文件时，Go 命令按所列文件组成一个包，绕过通常的构建约束筛选；go run main.go 也属于显式文件入口。它可能强行带入本应排除的文件，或遗漏本应自动配对的其他文件。应使用包路径或点来观察标签行为。官方加载实现设置了 UseAllFiles：https://go.dev/src/cmd/go/internal/load/pkg.go。

如果命令入口正确，再对照 IDE 的构建标签、实际工作目录、CI 的 GOFLAGS、目标平台及所用工具链。标签拼写区分大小写；文件名中出现 featurex 不替代注释。文件里写的是 //go:build featurex && linux，就不要只核对 featurex。先保留完整条件和命令，再判断哪个条件不满足。

收拢命名约定与常见疑问

修正后记录包路径、文件名、显式表达式、目标平台和附加标签，把对照命令放进构建说明。暂存的历史实现应移出包目录或明确限制，不能随意加一个 _linux 后缀充当“备份”。清空缓存不会解除一个仍然不满足的文件名条件，不必把它作为首个处理动作。

文件叫 probe_unix.go，是否自动限定 Unix？

不能仅靠这个名字。unix 是可用的构建标签，但不是具体 GOOS 名称；使用 //go:build unix 表达，另配互补实现。

为什么加标签后报 Mode 重复声明？

检查默认实现是否没有排除专用条件，导致两个文件同时选入。互补表达式需要对应专用文件的完整条件，不能只否定其中一个词。

测试能引用 Mode，普通构建却找不到，怎么查？

查看声明是不是放在 _test.go 中，并比较普通、包内测试和外部测试文件列表。生产实现不能依靠测试文件提供。

判断 build tags 是否有效，要看同一个包在同一组输入下选择了哪些文件，而不是只看编辑器里文件是否显示、文件名里有没有标签词。