Bazel构建Go项目必须显式注册匹配版本的toolchain、每个规则写对importpath、手动处理vendor/testdata；交叉编译须用--platforms而非环境变量。
Bazel 构建 Go 项目不是“装个工具就能跑”，必须显式注册 toolchain、每个规则写对 importpath、BUILD 文件缺一个就可能拉整个 GOPATH 进来编译——这是最常踩的三个坑。
WORKSPACE 中 go_register_toolchains() 版本必须和本地 go version 严格一致
你执行 go version 输出是 go version go1.22.4 darwin/arm64，那 go_register_toolchains() 就得写 go_register_toolchains(version = "1.22.4")。不匹配会导致 ERROR: no matching toolchain found for ... 或静默降级到系统默认 SDK（比如用上了 macOS 自带的旧版 go）。
常见错误现象：
- build 成功但运行时报
undefined symbol: runtime.cgo_yield（cgo 工具链没对上） -
bazel run //:main启动极慢，或 panic 在 init 阶段（SDK 内部 ABI 不兼容）
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 别抄网上过期示例里的固定版本（如
"1.16.5"），直接从go version提取数字部分 - 在 WORKSPACE 里加一行注释：
# go_version = $(go version | awk '{print $3}' | tr -d 'go')，提醒后续维护者 - CI 环境中用
goenv或asdf固定 Go 版本，并确保PATH和go_register_toolchains一致
每个 go_library/go_binary 规则都必须显式声明 importpath
importpath 不是可选字段，它对应 Go 源码里 import 语句的真实路径。Bazel 不会根据目录结构自动推断，漏写或拼错就会导致 no such package 或 import cycle not allowed。
使用场景举例：
- 你的包在
internal/auth目录下，importpath应为"myproject/internal/auth"，不是"internal/auth" - 主模块是
github.com/user/myproject，那cmd/server/main.go的importpath是"github.com/user/myproject/cmd/server"
容易踩的坑：
- 复制粘贴时删掉了引号，写成
importpath = myproject/cmd/server→ 解析失败 - 用了相对路径或短名（如
"server"），Go 编译器找不到导入目标 - 重构包路径后忘了同步改所有 BUILD.bazel 里的
importpath，导致新旧引用混用
gazelle update 默认不处理 vendor/ 和 testdata/，必须手动干预
gazelle update 默认只扫描 *.go 文件，且跳过 vendor/（设计如此）、testdata/、.git/ 等目录。如果你的 vendor/ 里有真实依赖（比如 go mod vendor 后），或者 testdata/ 下有内嵌测试用的 .go 文件（如 fake HTTP server），gazelle 就会完全忽略它们。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 运行前先确认已执行
go mod vendor，再用gazelle update -external vendored -from_root=. - 给 WORKSPACE 加
gazelle_config规则，指定build_file_name = ["BUILD.bazel"]和build_tags = ["integration"]（如有需要） -
testdata/xxx.go若需参与构建，必须手写一条go_library(name = "testdata", srcs = ["testdata/xxx.go"])，gazelle 永远不会自动生成
否则你会遇到：本地 go test 跑得通，bazel test //... 却报 cannot find package "xxx"，因为 vendor/testdata 根本没进构建图。
交叉编译必须用 --platforms，GOOS/GOARCH 环境变量完全无效
设 GOOS=linux GOARCH=arm64 bazel build //cmd/myapp 不会改变输出目标——Bazel 的 Go toolchain 切换靠 platform 声明，不是环境变量。不指定平台，永远走 host（即你当前机器）toolchain。
正确做法：
- 先查可用平台：
bazel query 'kind(platform, @local_config_platform//:*)' - 用官方预定义平台：
bazel build --platforms=@io_bazel_rules_go//go/toolchain:linux_arm64 //cmd/myapp - 自定义平台需写
platform规则并绑定constraint_values，不能只改 env
性能影响：
- 平台切换会触发完整 toolchain 下载（首次），缓存后增量快
- 不同平台间构建产物不共享缓存，
//cmd/myapp在 linux_amd64 和 darwin_arm64 下是两个独立 target
最容易被忽略的一点：如果你的项目含 cgo 代码，交叉编译时还必须确保对应平台的 C toolchain（如 gcc-arm-linux-gnueabihf）已配置进 Bazel，否则会卡在 C compiler not found。
