//go:build 必须紧贴文件顶部首行，前面不能有空行、注释或 license header，否则编译约束失效；多行 //go:build 是 AND 关系，自定义标签需显式用 -tags 启用。

go:build 必须紧贴文件顶部，前面不能有空行或注释

编译约束失效的最常见原因：在 //go:build 前插入了空行、文档注释、甚至 IDE 自动生成的 license header。Go 编译器只认「文件第一行就是 //go:build」这种格式，多一个空格或换行就当普通注释处理，整条约束被忽略。

• ✅ 正确写法：

  //go:build linux || darwin
  // +build linux darwin
  
  package main

• ❌ 错误写法（哪怕只多一个空行）：

  //go:build linux
  package main

  —— 这里开头的空行导致约束完全不生效
• ⚠️ 注意：// +build 是旧语法，虽仍支持，但必须和 //go:build 同时存在才能兼容 Go 1.17+；单独用 // +build 在新版本中可能被静默忽略

平台判断别写 runtime.GOOS == "xxx"，用 GOOS=linux 这类内置标签

运行时判断无法裁剪代码，runtime.GOOS == "windows" 这种写法会让所有平台的二进制都包含 Windows API 调用——Linux 上链接失败，体积还变大。真正起作用的是编译期剔除，必须靠 GOOS / GOARCH 标签。

• //go:build windows 等价于 //go:build GOOS=windows，直接启用官方预定义标签
• 组合条件优先用 && 或逗号：//go:build linux,amd64 表示仅 Linux + amd64 架构
• 避免硬编码字符串比较逻辑，比如 os.Getenv("PLATFORM") == "prod" —— 这不属于构建约束，无法控制编译行为

自定义标签（如 experimental）必须显式传 -tags 才生效

你写了 //go:build experimental，但 go build 默认不会启用它。内置平台标签（linux、darwin）是自动识别的，而自定义标签默认为 false，必须手动打开。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

• 启用方式：go build -tags=experimental 或 go build -tags="experimental debug"
• 多个标签用空格分隔，不是逗号：-tags="a b" ✅，-tags="a,b" ❌（会被当做一个标签名）
• CI/CD 中常漏掉这步，导致灰度功能代码没编译进去，线上跑的还是老逻辑

多个 go:build 行之间是 AND 关系，不是 OR

一个文件里写两行 //go:build，效果是「同时满足两者」，不是「满足任一即可」。这点容易误解，尤其当想表达「linux 或 windows，且带 debug 标签」时。

• 错误写法：

  //go:build linux || windows
  //go:build debug
  package main

  —— 实际意思是「(linux 或 windows) 且 debug」，但第二行会覆盖第一行的 OR 逻辑
• 正确写法（单行表达）：//go:build (linux || windows) && debug
• 更清晰的写法：//go:build linux,debug || windows,debug

实际项目里最容易被忽略的，是 //go:build 和 package 之间的那个空行 —— 它不是可选的格式美化，而是编译器识别约束的硬性分隔符。少它，整个条件编译就形同虚设。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！