Bazel 构建优化

Bazel 构建优化

在大规模 monorepo 中使用 Bazel 的生产实践模式。

不适用场景

• 任务与 Bazel 构建优化无关

• 需要此范围之外的其他领域或工具

指导原则

• 明确目标、约束条件和所需输入。

• 应用相关的最佳实践并验证结果。

• 提供可操作的步骤和验证方法。

• 如需详细示例，请打开 resources/implementation-playbook.md。

适用场景

• 为 monorepo 搭建 Bazel

• 配置远程缓存/执行

• 优化构建时间

• 编写自定义 Bazel 规则

• 调试构建问题

• 迁移至 Bazel

核心概念

1. Bazel 架构

workspace/
├── WORKSPACE.bazel       # 外部依赖
├── .bazelrc              # 构建配置
├── .bazelversion         # Bazel 版本
├── BUILD.bazel           # 根构建文件
├── apps/
│   └── web/
│       └── BUILD.bazel
├── libs/
│   └── utils/
│       └── BUILD.bazel
└── tools/
    └── bazel/
        └── rules/

2. 关键概念

| 概念 | 描述 |
|---------|-------------|
| Target (目标) | 可构建单元（库、二进制文件、测试） |
| Package (包) | 包含 BUILD 文件的目录 |
| Label (标签) | 目标的标识符 //path/to:target |
| Rule (规则) | 定义如何构建目标 |
| Aspect (切面) | 跨切面的构建行为 |

模板

模板 1: WORKSPACE 配置

# WORKSPACE.bazel
workspace(name = "myproject")
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
JavaScript/TypeScript 规则
http_archive(
    name = "aspect_rules_js",
    sha256 = "...",
    strip_prefix = "rules_js-1.34.0",
    url = "https://github.com/aspect-build/rules_js/releases/download/v1.34.0/rules_js-v1.34.0.tar.gz",
)
load("@aspect_rules_js//js:repositories.bzl", "rules_js_dependencies")
rules_js_dependencies()
load("@rules_nodejs//nodejs:repositories.bzl", "nodejs_register_toolchains")
nodejs_register_toolchains(
    name = "nodejs",
    node_version = "20.9.0",
)
load("@aspect_rules_js//npm:repositories.bzl", "npm_translate_lock")
npm_translate_lock(
    name = "npm",
    pnpm_lock = "//:pnpm-lock.yaml",
    verify_node_modules_ignored = "//:.bazelignore",
)
load("@npm//:repositories.bzl", "npm_repositories")
npm_repositories()
Python 规则
http_archive(
    name = "rules_python",
    sha256 = "...",
    strip_prefix = "rules_python-0.27.0",
    url = "https://github.com/bazelbuild/rules_python/releases/download/0.27.0/rules_python-0.27.0.tar.gz",
)
load("@rules_python//python:repositories.bzl", "py_repositories")
py_repositories()

模板 2: .bazelrc 配置

# .bazelrc
构建设置
build --enable_platform_specific_config
build --incompatible_enable_cc_toolchain_resolution
build --experimental_strict_conflict_checks
性能优化
build --jobs=auto
build --local_cpu_resources=HOST_CPUS*.75
build --local_ram_resources=HOST_RAM*.75
缓存
build --disk_cache=~/.cache/bazel-disk
build --repository_cache=~/.cache/bazel-repo
远程缓存（可选）
build:remote-cache --remote_cache=grpcs://cache.example.com
build:remote-cache --remote_upload_local_results=t

远程执行（可选）

平台配置

CI 配置

测试设置

覆盖率

便捷别名

导入用户设置

### 模板 3：TypeScript 库 BUILD

libs/utils/BUILD.bazel

npm_link_all_packages(name = "node_modules")

ts_project(
name = "utils_ts",
srcs = glob(["src/**/*.ts"]),
declaration = True,
source_map = True,
tsconfig = "//:tsconfig.json",
deps = [
":node_modules/@types/node",
],
)

js_library(
name = "utils",
srcs = [":utils_ts"],
visibility = ["//visibility:public"],
)

测试

jest_test(
name = "utils_test",
config = "//:jest.config.js",
data = [
":utils",
"//:node_modules/jest",
],
node_modules = "//:node_modules",
)

### 模板 4：Python 库 BUILD

libs/ml/BUILD.bazel

py_library(
name = "ml",
srcs = glob(["src/**/*.py"]),
deps = [
requirement("numpy"),
requirement("pandas"),
requirement("scikit-learn"),
"//libs/utils:utils_py",
],
visibility = ["//visibility:public"],
)

py_test(
name = "ml_test",
srcs = glob(["tests/**/*.py"]),
deps = [
":ml",
requirement("pytest"),
],
size = "medium",
timeout = "moderate",
)

py_binary(
name = "train",
srcs = ["train.py"],
deps = [":ml"],
data = ["//data:training_data"],
)

### 模板 5：Docker 自定义规则

tools/bazel/rules/docker.bzl

# 构建镜像
output = ctx.actions.declare_file(ctx.attr.name + ".tar")

args = ctx.actions.args()
args.add("--dockerfile", dockerfile)
args.add("--output", output)
args.add("--base", base_image)
args.add_all("--layer", layers)

ctx.actions.run(
inputs = [dockerfile] + layers,
outputs = [output],
executable = ctx.executable._builder,
arguments = [args],
mnemonic = "DockerBuild",
progress_message = "Building Docker image %s" % ctx.label,
)

return [DefaultInfo(files = depset([output]))]

docker_image = rule(
implementation = _docker_image_impl,
attrs = {
"dockerfile": attr.label(
allow_single_file = [".dockerfile", "Dockerfile"],
mandatory = True,
),
"

### 模板 6：查询与依赖分析

查找目标的全部依赖

查找反向依赖（谁依赖于此目标）

查找包中的所有目标

查找自上次提交以来变更的目标

生成依赖图

查找所有测试目标

查找具有特定标签的目标

计算构建图规模

### 模板 7：远程执行配置

platforms/BUILD.bazel

platform(
name = "remote_linux",
parents = [":linux_x86_64"],
exec_properties = {
"Pool": "default",
"dockerNetwork": "standard",
},
)

toolchains/BUILD.bazel

## 性能优化

构建分析 (Profiling)

识别慢速操作

内存分析

跳过分析缓存

最佳实践

推荐做法 (Do's)

• 使用细粒度目标 —— 提高缓存命中率

• 锁定依赖版本 —— 确保构建可复现

• 启用远程缓存 —— 共享构建产物

• 合理设置可见性 (Visibility) —— 强制执行架构规范

• 按目录编写 BUILD 文件 —— 遵循标准约定

避免做法 (Don'ts)

• 不要在依赖中使用 glob —— 显式声明优于隐式

• **不要提交 bazel-* 目录 —— 将其添加到 .gitignore

• 不要忽略 WORKSPACE 配置 —— 它是构建的基石

• 不要忽略构建警告** —— 避免积累技术债

相关资源

• Bazel 官方文档

• Bazel 远程执行

• rules_js

局限性

• 仅在任务明确符合上述范围时使用此技能。

• 不要将输出结果视为环境特定验证、测试或专家评审的替代方案。

• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。