用 Bazel 进行构建

Building with Bazel

本章讲解了如何使用 Bazel 来构建和测试 Angular 应用。

This guide explains how to build and test Angular apps with Bazel.

本指南假设你已经熟悉如何使用 CLI 来开发和构建 Angular 应用了。

This guide assumes you are already familiar with developing and building Angular applications using the CLI.

这里描述的这些特性是 Angular Labs 的一部分,因此不是稳定的、受支持的 API。

It describes features which are part of Angular Labs, and are not considered a stable, supported API.

在 Angular CLI 中使用 Bazel

Using Bazel with the Angular CLI

@angular/bazel 包提供了一个构建器,允许 Angular CLI 使用 Bazel 作为构建工具。

The @angular/bazel package provides a builder that allows Angular CLI to use Bazel as the build tool.


To opt-in an existing application, run

ng add @angular/bazel
      ng add @angular/bazel

要在新的应用中使用 Bazel,首先要全局安装@angular/bazel

To use Bazel in a new application, first install @angular/bazel globally

npm install -g @angular/bazel
      npm install -g @angular/bazel


then create the new application with

ng new --collection=@angular/bazel
      ng new --collection=@angular/bazel

当你使用 Angular CLI 的构建类命令时(比如 ng buildng serve),Bazel 会在幕后工作。 Bazel 的输出会显示在 dist/bin 文件夹中。

Now when you use Angular CLI build commands such as ng build and ng serve, Bazel is used behind the scenes. Outputs from Bazel appear in the dist/bin folder.

命令行输出中还包括来自 Bazel 的额外日志记录。我们计划在未来减少这种情况。

The command-line output includes extra logging from Bazel. We plan to reduce this in the future.

去掉 Bazel

Removing Bazel

如果你不想使用 Bazel,你可以恢复备份文件:

If you need to opt-out from using Bazel, you can restore the backup files:

  • /angular.json.bak 替换 /angular.json

    /angular.json.bak replaces /angular.json


Advanced configuration

编辑这份 Bazel 配置可以防止你有选择的退出 Bazel。 Bazel 驱动的自定义行为在其它构建器中是无用的。

Editing the Bazel configuration may prevent you opting out of Bazel. Custom behaviors driven by Bazel won't be available in other Builders.

本节假设你熟悉 Bazel

This section assumes you are familiar with Bazel.

你可以手动把 Bazel 配置调整为:

You can manually adjust the Bazel configuration to:

  • 自定义构建步骤

    customize the build steps

  • 构建过程并行化,以支持可延展性和增量构建

    parallellize the build for scale and incrementality

运行以下命令,创建初始的 Bazel 配置文件:

Create the initial Bazel configuration files by running the following command:

ng build --leaveBazelFilesOnDisk
      ng build --leaveBazelFilesOnDisk

在 Angular 工作区中,你会找到一些新文件:

Now you'll find new files in the Angular workspace:

  • /WORKSPACE 会告诉 Bazel 要如何下载外部依赖。

    /WORKSPACE tells Bazel how to download external dependencies.

  • /BUILD.bazel/src/BUILD.bazel 会告诉 Bazel 你的源代码在哪里。

    /BUILD.bazel and /src/BUILD.bazel tell Bazel about your source code.

你可以在 https://github.com/bazelbuild/rules_nodejs/tree/master/examples/angular 找到一个全功能的 Bazel 配置示例。

You can find a full-featured example with custom Bazel configurations at https://github.com/bazelbuild/rules_nodejs/tree/master/examples/angular.

https://docs.bazel.build/versions/master/bazel-and-javascript.html 则是一个关于如何使用 Bazel 进行前端项目的文档链接。

Documentation for using Bazel for frontend projects is linked from https://docs.bazel.build/versions/master/bazel-and-javascript.html.

直接运行 Bazel

Running Bazel directly

在某些情况下,你会想要绕过 Angular CLI 的构建器,并直接运行Bazel CLI。 Bazel CLI 位于 @bazel/bazel npm 包中。你可以全局安装它,以便你能通过路径获取 bazel 命令,或者用 $(npm bin)/bazel 代替下面的 bazel。

In some cases you'll want to bypass the Angular CLI builder, and run the Bazel CLI directly. The Bazel CLI is in the @bazel/bazel npm package. You can install it globally to get the bazel command in your path, or use $(npm bin)/bazel in place of bazel below.

Bazel 的常用命令有:

The common commands in Bazel are:

  • bazel build [targets]:编译指定目标的默认输出成果。

    bazel build [targets]: Compile the default output artifacts of the given targets.

  • bazel test [targets]:对于那些符合 *_test 模式的目标,运行测试。

    bazel test [targets]: For whichever *_test targets are found in the patterns, run the tests.

  • bazel run [target]:编译目标所代表的程序,然后运行它。

    bazel run [target]: Compile the program represented by target, and then run it.

要想在输入发生变化时重复执行此命令(即 watch 模式),请把这些命令中的 bazel 替换为 ibazel

To repeat the command any time the inputs change (watch mode), replace bazel with ibazel in these commands.


The output locations are printed in the output.

Bazel CLI 的完整文档位于 https://docs.bazel.build/versions/master/command-line-reference.html

Full documentation for the Bazel CLI is at https://docs.bazel.build/versions/master/command-line-reference.html.


Querying the build graph

Bazel 会根据你的目标构造一个图谱,你可以从中找到很多有用的信息。

Because Bazel constructs a graph out of your targets, you can find lots of useful information.

使用一个名叫 graphviz 的可选依赖,可以得到一个名叫 dot 的程序,这样你就可以用它来进行 bazel query 了:

Using the graphviz optional dependency, you'll have a program dot, which you can use with bazel query:

$ bazel query --output=graph ... | dot -Tpng > graph.png
      $ bazel query --output=graph ... | dot -Tpng > graph.png

关于 bazel query 的详细信息,参见 https://docs.bazel.build/versions/master/query-how-to.html

See https://docs.bazel.build/versions/master/query-how-to.html for more details on bazel query.

自定义 BUILD.bazel 文件

Customizing BUILD.bazel files

“规则(Rules)”就好比 Bazel 的插件。有很多可用的规则集。本指南记录了 Angular 开发组在 Google 所做的一部分工作。

"Rules" are like plugins for Bazel. Many rule sets are available. This guide documents the ones maintained by the Angular team at Google.

BUILD.bazel 文件中用到了一些规则,这些规则都是工作空间中各个包的标记。每个 BUILD.bazel 文件都会向 Bazel 声明一个单独的包。你也可以使用更粗粒度的发布方式,但这样一来你发布的包(例如,到npm )就会由很多个 Bazel 包组合而成。

Rules are used in BUILD.bazel files, which are markers for the packages in your workspace. Each BUILD.bazel file declares a separate package to Bazel, though you can have more coarse-grained distributions so that the packages you publish (for example, to npm) can be made up of many Bazel packages.

BUILD.bazel 文件中,必须首先使用 load 语句导入每个规则。然后用一些属性调用此规则,调用此规则的结果就是向 Bazel 中声明了:当给定一些输入和依赖的时候该如何得到一些输出。然后,当你运行一个 bazel 命令时,Bazel 就会加载你声明过的所有规则,以确定它们在运行期间的绝对顺序。注意,只有那些在产生输出时真正起作用的规则才会被执行。

In the BUILD.bazel file, each rule must first be imported, using the load statement. Then the rule is called with some attributes, and the result of calling the rule is that you've declared to Bazel how it can derive some outputs given some inputs and dependencies. Then later, when you run a bazel command line, Bazel loads all the rules you've declared to determine an absolute ordering of what needs to be run. Note that only the rules needed to produce the requested output will actually be executed.

https://github.com/bazelbuild/rules_nodejs/ 上的 README 文件中记录了前端开发中要用到的通用规则列表。

A list of common rules for frontend development is documented in the README at https://github.com/bazelbuild/rules_nodejs/.