Bazel并非Go项目必需，除非存在依赖隔离、跨语言协同或千级target增量构建瓶颈；盲目引入易致规则维护难、版本冲突及错误定位困难。
Go项目用Bazel构建前，先确认你真需要它
Bazel不是Go项目的默认选择，也不是“更先进”的替代品。如果你的项目没遇到go build无法解决的依赖隔离、跨语言协同（比如混C++/Python）、或千级target的增量构建瓶颈，加Bazel大概率是增加复杂度而非解决问题。
常见踩坑点：团队里没人维护过Bazel规则，但硬上rules_go，结果WORKSPACE里一堆http_archive版本冲突，go_library编译失败却报错在bazel-out路径里，根本看不出哪行代码惹的祸。
- 单语言纯Go项目（go mod +
go build -o，快且稳定 - 需要和Java/JS/C++共用同一套CI缓存、强制统一构建约束、或做细粒度build graph分析：Bazel才有实际收益
- Monorepo里已有非Go代码，并且已用Bazel管理：那Go部分必须对齐，否则CI割裂
rules_go版本和Go SDK绑定必须显式声明
rules_go不自动适配本地go命令版本，它自己下载并管理Go SDK。如果WORKSPACE里写的是go_version = "1.21.0"，但你的go.mod要求go 1.22，Bazel会静默用旧版SDK编译——可能成功，但运行时panic（比如io.ReadAll行为变化）。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在
WORKSPACE中用go_register_toolchains明确指定version，不要依赖default_version - 把
go.mod里的go版本和rules_go声明的go_version写成一样，CI里加校验脚本比对两者 - 避免在
go_binary里设gc_linkopts绕过SDK限制——这会让不同target用不同linker，最终二进制不一致
go_library的importpath必须和模块路径严格匹配
Bazel里go_library的importpath不是可选字段，它决定符号可见性与依赖解析。如果importpath = "example.com/foo/bar"，但实际代码里import "example.com/foo/baz"，Bazel不会报错，而是静默忽略该import——编译通过，运行时报no such file or directory。
典型场景：
- Monorepo下多个Go模块共享一个
WORKSPACE，每个模块有自己的go.mod，但importpath写成绝对路径（如github.com/org/repo/sub），而代码里用相对导入（import "./sub"）→ 失败 - 重构包路径后只改了
go.mod没同步importpath→ Bazel认为这是两个独立库，导致重复编译、符号冲突 - 用
go_repository拉第三方依赖时，importpath由规则自动生成，但若该库用了replace指向本地路径，Bazel无法感知，仍按原始路径解析
测试覆盖率和race检测得手动打开，且行为和go test不同
Bazel默认不开启-race或-cover，即使你在go_test里写了gc_goopts = ["-race"]，也只影响编译阶段，不触发运行时检测。真正生效要靠--features=race全局flag，但这个flag会影响所有Go target，包括go_library，可能引发不兼容。
关键差异：
-
go test -race跑完直接输出竞争报告；Bazel需额外加--test_output=all --test_arg=-test.run=^$ --test_arg=-test.coverprofile=coverage.out才能拿到覆盖数据 - Bazel的
go_test默认不继承GOOS/GOARCH环境变量，交叉测试要显式写env = {"GOOS": "linux"} - 使用
golang.org/x/tools/cmd/goimports这类工具链时，Bazel里必须定义go_binary并用data带上.goimportsrc，否则格式化行为和本地不一致
最常被忽略的是：Bazel的sandbox机制会让os.Getwd()返回临时路径，任何依赖当前工作目录读配置、找资源文件的测试都会失败——得用runfiles API显式定位。
