# Bazel 项目视图

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/idea/llms.txt).

一个  Bazel 项目视图  是 IntelliJ IDEA 用于以下目的的配置：

* 决定从 Bazel 工作区中导入/索引哪些部分

* 决定为诸如代码导航、代码补全、运行配置和测试等功能同步哪些 Bazel 目标

* 将 Bazel 标志和其他设置应用于从 IntelliJ IDEA 启动的同步和构建操作。

当您只需要一个或多个子树时，Bazel 项目视图可防止拉取整个 Bazel 工作区。 它不会改变 Bazel 的工作方式，而是限定 Bazel 和 IntelliJ IDEA 执行的工作范围。 这将提升性能，并使项目更易于使用。

## 项目视图配置

项目视图在  `.bazelproject`  文件中进行配置。 您的项目中可能在任意位置包含多个此类文件。 有关  `.bazelproject`  文件语法的信息，请参阅 [.bazelproject 文件参考](#bazelproject_reference) 章节。

> **Tip:**
> 如果您的团队成员在处理项目的同一子集，您可以创建一个  `.bazelproject`  文件，并 [通过 VCS 共享它](version-control-integration.html)。 这将确保每个人都能获得一致的项目视图。

## 导航到当前项目视图

如果您不确定当前活动的项目视图配置在何处，IDE 可以将您导航到相应的文件。

Procedure:

1. 在右侧边栏，点击   Bazel   图标。 或者，从主菜单中选择  `视图 | 工具窗口 | Bazel` 。

![右侧边栏上的 Bazel 工具窗口图标](https://resources.jetbrains.com/help/img/idea/2026.3/bazel-tw-icon.png)

2. 点击   在编辑器中打开项目视图文件   按钮。

![Bazel 工具窗口中的 '在编辑器中打开项目视图文件' 按钮](https://resources.jetbrains.com/help/img/idea/2026.3/bazel-open-project-view.png)

## 选择项目视图

当工作区中存在多个项目视图时，您可以在它们之间切换。

Procedure:

* 在   项目   工具窗口中：右键点击一个  `.bazelproject`  文件，然后选择   加载项目视图  。

* 在设置 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 中：转到  `构建、执行、部署 | 构建工具 | Bazel` ，然后在   项目视图路径   字段中输入  `.bazelproject`  文件的路径。

## .managed.bazelproject

有一种特殊类型的 .bazelproject 文件会签入到你的代码库中，并归代码库维护者所有。 要定义中央模板，请将其放在  `tools/intellij/.managed.bazelproject`  中。 它用于为大型代码库和短期的远程开发环境等场景提供默认的最小视图。

以下是两种项目视图之间差异的简要概述：

|  |   `.managed.bazelproject`   |   `.bazelproject`   |
| --- | --- | --- |
|  用途  |  供你的组织/代码库使用的规范、集中维护的项目视图模板。  |  IntelliJ IDEA 在索引/构建时实际读取的具体项目视图。  |
|  位置  |  位于你的代码库下，通常在  `tools/intellij/.managed.bazelproject`   |  在你的检出中生成，位置为  `.bazelbsp/.bazelproject`   |
|  所有权  |  由代码库（代码所有者、构建团队）维护。  |  由插件创建的按用户、按工作副本生成的制品。  |
|  VCS  |  已提交到 VCS。  |  通常不会提交；会被视为生成的文件。  |
|  预期编辑  |  通常不要在本地编辑此项，除非要为所有人更改共享模板。  |  可以在此处进行本地微调，但不会与其他人共享。  |

打开包含  `.managed.bazelproject`  文件的新项目时，IntelliJ IDEA 会基于该文件生成  `.bazelproject`  文件。

项目视图解析的优先级顺序为：

* `{project root}/.bazelproject`

* `managed.bazelproject` 会复制到 `{project root}/.bazelbsp/.bazelproject` – 可通过 `设置 | 构建、执行、部署 | 构建工具 | Bazel` 配置

* 使用以下设置创建默认 `{project root}/bazelbsp/.bazelproject` ： ``` derive_targets_from_directories: true directories: . ```

## .bazelproject 文件参考

项目视图文件被划分为具名节，并使用类似 Python 的格式，采用两个空格缩进。

### 文件和节语法

* 从 `#` 之后到换行符为止的内容被视为注释。

* 节标题 位于行首，并使用 `名称：内容` 或 `名称 内容` 格式。 在节名后可以使用空格或冒号。

* 节正文 一直延续到下一个节标题。

### 节类型

所有具名节均属于以下类型之一：

* 单值节 ：一个值（Boolean、Int、Path 或 String），例如： ```TEXT derive_targets_from_directories: true import_depth 2 ```

* 列表节 ：多个值，以空格或换行分隔，例如： ```TEXT build_flags: --config=ci --cxxopt=-O2 ```

* 可排除的列表节 ：多个值，以空格或换行分隔；以 `-` 开头的条目将被排除。 例如： ```TEXT targets: //app:all -//app:tests ```

### 可重复的节

节可以出现多次。 如果发生这种情况，将应用以下解析规则：

* 单值节：以最后一次出现为准。

* 列表节：按出现顺序合并这些节。

* 可排除的列表节：与常规列表节相同，包含列表与排除列表均按出现顺序合并。

### 导入

项目视图可以使用  `import`  和  `try_import`  导入其他项目视图。

* `import path/to/file.bazelproject` 必需的导入。 如果找不到该文件，则项目视图被视为无效。

* `try_import path/to/optional.bazelproject` 可选的导入。 如果找不到该文件，即使不导入其他项目视图，项目视图仍然有效。

IntelliJ IDEA 会先解析所有  `import`  条目，然后按照它们在文件中的出现顺序解析所有  `try_import`  条目。 在完成导入后，将处理当前文件自身的各节。

您可以在项目视图中使用多个导入。 在这种情况下，导入的列表节（例如，  `targets` ）会被合并，单值节（例如，  `bazel_binary` ）会覆盖先前遇到的值。

### 节参考

以下是按类型分组的全部可用节的完整列表。 有关节类型及其语法的列表，请参阅 [节类型](#section_types) 章节。

#### 可排除的列表节

targets (List<Path>)
: 要包含在导入中的一组 Bazel 目标。 支持用于包的递归通配符（  `/...` ）。 目标越多，您的 IDE 使用体验可能越慢。
:
:
:
: 示例：
:
:
:
:
: ```
: targets:
: //install/src/main/kotlin/org/jetbrains/bazel/install
: //executioncontext/projectview/...
: -//executioncontext/projectview/src/main/kotlin/org/jetbrains/bazel/projectview/parser/...
:
: ```

directories (List<Path>)
: 要映射为 Bazel 目标的目录。 可与 [derive_targets_from_directories](#derive_targets_from_directories) 一起使用，通过扫描指定目录自动发现相关目标。
:
:
:
: 示例：
:
:
:
:
: ```
: directories:
: install/src/main/kotlin/org/jetbrains/bazel/install
: executioncontext/projectview/
: -executioncontext/projectview/src/main/kotlin/org/jetbrains/bazel/projectview/parser
:
: ```

#### 列表节

build_flags (List<String>)
: 随所有 Bazel 命令调用一起传递的一组 Bazel 标志。 默认情况下，不传递任何标志。
:
:
:
: 示例：
:
:
:
:
: ```
: build_flags:
: --define=ij_product=intellij-latest
:
: ```

sync_flags (List<String>)
: 在同步期间随 Bazel 命令调用一起传递的一组 Bazel 标志。 默认情况下，不传递任何标志。
:
:
:
: 示例：
:
:
:
:
: ```
: sync_flags:
: --define=ij_product=intellij-latest
:
: ```

test_flags (List<String>)
: 将在未来的版本中支持。

debug_flags (List<String>)
: 在调试模式下传递给  `bazel run`  的一组 Bazel 标志。
:
:
:
: 示例：
:
:
:
:
: ```
: debug_flags:
: --cxxopt=-g
:
: ```

enabled_rules (List<String>)
: 显式声明您的项目应启用哪些外部 Bazel 规则集，并覆盖自动检测（对于某些设置，自动检测可能不完整）。
:
:
:
: 示例：
:
:
:
:
: ```
: enabled_rules:
: rules_java
: rules_kotlin
:
: ```

import_run_configurations (List<Path>)
: 在 Bazel 同步期间作为运行配置导入的 XML 文件列表。
:
:
:
: 示例：
:
:
:
:
: ```
: import_run_configurations:
: tools/intellij/run_application.xml
: tools/intellij/run_tests.xml
:
: ```
:
:
:
: > **Note:**
: > 来自 Google 的 Bazel 插件的运行配置在导入时将自动转换为新格式。
:
:
:
: > **Tip:**
: > 有关将运行配置导出为 XML 的信息，请参阅 [共享运行/调试配置](run-debug-configuration.html#share-configurations)

java_source_root_optimization_patterns（List<字符串>）
: 指定用于优化软件包推断的源目录的全局模式。 本节与 [java_source_root_optimization_enable](#java_source_root_optimization_enable)一同使用。
:
:
:
: 其路径至少匹配其中一个模式的源文件，其软件包通过批量优化进行派生。 其他源文件的软件包信息将从各自文件中读取。
:
:
:
: 默认模式：  `src/main/java` 、  `src/test/java` 、  `src/main/kotlin` 、  `src/test/kotlin` 、  `src/java`  和  `src/kotlin` 。
:
:
:
: `*`  将优化应用于所有源目录。
:
:
:
: 示例：
:
:
:
:
: ```
: java_source_root_optimization_patterns:
: src/main/kotlin
:
: ```

python_code_generator_rule_names (List<String>)
: 指定应将哪些 Bazel 规则类型视为 Python 代码生成器。
:
:
:
: 示例：
:
:
:
:
: ```
: python_code_generator_rule_names:
: my_py_codegen_rule
: another_py_codegen
:
: ```

index_additional_files_in_directories（List<字符串>）
: 指定供 IntelliJ IDEA 索引的文件名或文件全局模式，补充目标已经定义的源文件、资源和库。
:
:
:
: 为了加快索引速度，IntelliJ IDEA 只索引属于 Bazel 目标的文件。 此操作可能会排除某些文件，比如  `*.xml`  配置文件、  `package.json`  或其它未直接出现于目标资源部分的非源文件。 这意味着它们的搜索会变慢，部分 IntelliJ IDEA 功能（包括跳转到定义和用法导航）将无法使用。
:
:
:
: 本节中的模式会与一组始终索引的内置默认设置合并：
:
:
:
: * `WORKSPACE` / `WORKSPACE.bazel` 文件
:
: * `BUILD` / `构建.bazel` 文件
:
: * `MODULE.bazel`
:
:
:
: 示例：
:
:
:
:
: ```
: index_additional_files_in_directories:
: *.xml
: package.json
:
: ```
:
:
:
: > **Note:**
: > 当 [index_all_files_in_directories](#index_all_files_in_directories) 为  `true`  时，本节不适用

#### 单值节

bazel_binary (Path)
: 指向 Bazel 的路径，服务器将在构建项目或运行 Bazel 查询等操作中使用它。 如果未指定，服务器将使用  `$PATH`  变量中的二进制文件。
:
:
:
: 示例：
:
:
:
:
: ```
: bazel_binary: /usr/local/bin/bazel
: ```

derive_targets_from_directories (Boolean)
: 指定是否应从  `directories`  节中的目录派生目标。 默认情况下，不派生目标（  `false` ），但这些目录不会从项目视图中排除。
:
:
:
: 示例：
:
:
:
:
: ```
: derive_targets_from_directories: true
: ```

import_depth (Int)
: 指定应将 Bazel 目标的依赖项导入为模块的层级数。 仅导入工作区中存在的目标。 您可以使用负值导入所有传递依赖项。 默认值为  `-1` ，表示包含所有传递上下文。
:
:
:
: 示例：
:
:
:
:
: ```
: import_depth: 1
:
: ```

allow_manual_targets_sync (Boolean)
: 允许同步被标记为 manual 的目标。 默认情况下（  `false` ），仅 manual 的目标会被跳过。
:
:
:
: 示例：
:
:
:
:
: ```
: allow_manual_targets_sync: true
:
: ```

ide_java_home_override (Path)
: 覆盖 IntelliJ IDEA 在同步和 IDE 操作期间用于 Java 目标的  `JAVA_HOME` 。 它会覆盖本应从 Bazel 的 Java 工具链/运行时推断出的 JDK。 Bazel 本身仍将使用其已配置的工具链进行构建；此覆盖仅在 IDE 中生效。
:
:
:
: 示例：
:
:
:
:
: ```
: ide_java_home_override:
: /Users/me/Library/Java/JavaVirtualMachines/jbr-21
:
: ```

shard_sync (Boolean)
: 允许将 Bazel 同步/构建拆分为更小的批次（也称为分片），而不是执行一次性同步/构建。 这有助于避免 Bazel 内存不足，并在同步大量目标时减少命令行过长等问题。 默认值为  `false` ，这是由于 Bazel 存在 [潜在的内存泄漏问题](https://github.com/bazelbuild/bazel/issues/19412)。
:
:
:
: 示例：
:
:
:
:
: ```
: shard_sync: true
:
: ```

target_shard_size (Int)
: 指定每个分片中要构建的目标数量。 默认值为  `1000` 。
:
:
:
: 示例：
:
:
:
:
: ```
: target_shard_size: 500
:
: ```

shard_approach (String)
: 指定对原始目标列表进行分片所使用的策略。 与 [shard_sync](#shard_sync) 结合使用。 默认值为  `QUERY_AND_SHARD` 。
:
:
:
: 可能的取值如下：
:
:
:
: * `EXPAND_AND_SHARD` ：将通配符目标展开为包目标，查询单个目标，然后分片成批次
:
: * `QUERY_AND_SHARD` ：不展开，从给定的目标列表中查询单个目标，然后分片成批次
:
: * `SHARD_ONLY` ：将未展开的通配符目标拆分为批次
:
:
:
: 示例：
:
:
:
:
: ```
: shard_approach: EXPAND_AND_SHARD
:
: ```

gazelle_target (String)
: 指定 IntelliJ IDEA 是否应在每次 Bazel 同步开始时自动运行 Gazelle 目标。 在 IntelliJ IDEA 收集目标并索引源之前，这会为项目视图中包含的目录更新或生成 BUILD 文件。
:
:
:
: 示例：
:
:
:
:
: ```
: gazelle_target: //tools/gazelle:gazelle
:
: ```

index_all_files_in_directories (Boolean)
: 指定 IntelliJ IDEA 是否应索引  `directories`  节所列目录下的所有文件，而不论这些文件是否属于 Bazel 目标。 这可加快对非目标源、文档或脚本的搜索与导航，但在单体仓库或大型项目中，索引本身可能较慢且占用大量内存。 默认值为  `false` 。
:
:
:
: 示例：
:
:
:
:
: ```
: index_all_files_in_directories: true
:
: ```

import_ijars (Boolean)
: 指定在导入期间，针对 JVM 库是否优先使用接口/头部 jar（ijar），而不是完整 jar。 接口/头部 jar 仅包含公共 API 类存根，而不包含完整字节码。 这可减小索引大小并提升导入性能，但会影响导航到库实现，并可能在某些 IDE 警告中产生误报。 默认值为  `false` 。
:
:
:
: 示例：
:
:
:
:
: ```
: import_ijars: true
:
: ```

java_source_root_optimization_enable（布尔值）
: 启用 Java 源根优化。
:
:
:
: 未启用该优化时，IntelliJ IDEA 通过读取各文件对应声明获取 Java、Kotlin 或 Scala 源文件的软件包信息。
:
:
:
: 在大型单仓库中，读取每个源文件的软件包信息可能较慢。 启用  `java_source_root_optimization_enable`  后，IntelliJ IDEA 会使用 [java_source_root_optimization_patterns](#java_source_root_optimization_patterns)中指定的模式，批量解析文件的软件包，从而减少 I/O 开销。 默认值为  `false` 。
:
:
:
: 示例：
:
:
:
:
: ```
: java_source_root_optimization_enable: true
:
: ```

run_config_run_with_bazel（布尔值）
: 控制运行配置是使用 Bazel（  `bazel run` /  `bazel test` ）执行，还是通过 [--script_path](https://bazel.build/reference/command-line-reference#run-flag--script_path) 执行。
:
:
:
: 启用后，Bazel 会处理完整执行，从而可以利用 Bazel 的测试结果缓存和远程构建执行（RBE）。 但这样做的代价是，Bazel 在执行期间会获取工作区锁，因此无法并行运行多个运行配置。
:
:
:
: 禁用时，IntelliJ IDEA 会通过 Bazel 编译目标，但直接启动生成的二进制文件，从而绕过 Bazel 锁。
:
:
:
: > **Note:**
: > 调试时，该设置会被忽略：调试会话绝不会使用 Bazel 执行。
:
:
:
: 默认值为  `true` 。
:
:
:
: 示例：
:
:
:
:
: ```
: run_config_run_with_bazel: false
:
: ```

derive_instrumentation_filter_from_targets (Boolean)
: 指定是否计算并添加  `--instrumentation_filter` ，其包含所有已导入目标的 Bazel 包。 当  `false`  时，不添加插桩过滤器，或者您可以使用  `.bazelrc`  指定它。 例如，  `coverage --instrumentation_filter="^//"` 。 默认值为  `true` 。
:
:
:
: 示例：
:
:
:
:
: ```
: derive_instrumentation_filter_from_targets: false
:
: ```

