Bazel 远程执行排查指南：用 Workspace Rules 日志定位 WORKSPACE 规则中的非 Hermetic 行为

Bazel 远程执行排查指南：用 Workspace Rules 日志定位 WORKSPACE 规则中的非 Hermetic 行为

【免费下载链接】bazela fast, scalable, multi-language and extensible build system项目地址: https://gitcode.com/GitHub_Trending/ba/bazel

导读

在 Bazel 远程执行（remote execution）场景下，构建与测试步骤被发送到远端 worker 执行，但WORKSPACE 仓库规则的解析与执行仍发生在宿主机（host machine）上。一旦仓库规则悄悄读取了宿主机的环境信息（如路径、程序、环境变量、平台特性），本地与远端环境的不一致就会导致构建在远端莫名失败。本文基于 Bazel 官方文档 docs/remote/workspace.mdx，系统讲解如何借助--experimental_workspace_rules_log_file生成的 workspace 日志，逐条定位并修复这些潜在的非 hermetic 行为。读完本文，你将掌握一套完整的"生成日志 → 解析日志 → 分类审查 → 修复规则"的可操作排查流程。

为什么 WORKSPACE 规则会成为远程执行的隐患

先厘清一个关键事实：宿主机是运行 Bazel 的那台机器。当启用远程执行时，实际的构建/测试步骤不再发生在宿主机上，而是被发送到远程执行系统；然而，解析 workspace 规则所涉及的步骤（仓库规则、模块扩展的执行）全部在宿主机本地完成。

如果你的 workspace 规则在执行期间访问了宿主机的信息，由于本地与远端 worker 环境存在差异，构建极有可能因此失败。这是远程执行迁移中最隐蔽的失败来源之一——问题往往不会在本地暴露，只有在远端环境差异显现时才突然出现。

因此，作为适配 Bazel 规则以支持远程执行工作的一部分，你需要找出这类 workspace 规则并修复它们。本文描述的就是如何借助 workspace 日志来定位可能存在问题的规则。

非 Hermetic 行为的来源：repository_ctx

仓库规则允许开发者向外部 workspace 添加依赖，但它的能力足够丰富，可以在规则执行过程中做任意处理。所有相关命令都在本地（宿主机）执行，因此每一步都可能成为非 hermetic 行为的来源。

通常，非 hermetic 行为是通过repository_ctx引入的——这是 Starlark 中与宿主机交互的核心内置对象，它暴露了execute、download、file、template、os、symlink、which等与宿主环境直接打交道的方法。这些方法本身并不都"有罪"，但它们是宿主环境依赖进入构建图的典型通道，也正是 workspace 日志重点记录的审计对象。

开启 Workspace 日志：一条 flag 捕获全部可疑操作

自 Bazel 0.18 起，可以在 Bazel 命令中追加如下 flag 来记录一部分潜在的非 hermetic 操作：

--experimental_workspace_rules_log_file=[PATH]

其中[PATH]是日志文件的输出路径。该 flag 在 Bazel 源码中的定义位于 DebuggingOptions.java，属于 verbosity 类别、LOGGING 文档分类，其说明为"将某些 Workspace Rules 事件以分隔的 WorkspaceEvent proto 形式记录到该文件"。

使用该日志时需要注意以下三点：

1. 日志按事件实际执行顺序捕获。如果某些步骤命中了缓存，它们不会出现在日志中。要获得完整结果，不要忘记先执行bazel clean --expunge。
2. 有些函数可能会被重新执行，此时相关事件会在日志中多次出现，这是正常现象。
3. workspace 规则目前只记录 Starlark 事件。另外，只要指定了哈希值（hash），某些规则并不会引起 hermiticity 问题（例如指定sha256的下载）。

日志的底层格式：WorkspaceEvent proto

日志文件是一个二进制 proto 文件，由一系列WorkspaceEvent消息构成（以 delimited 形式连续写入）。消息定义位于 workspace_log.proto，其核心结构如下：

• location：事件在代码（.bzl 文件）中产生的位置；
• context：事件发生的上下文，可以是repository @foo，或module extension foo in @bar//:quux.bzl；
• event（oneof）：具体事件负载，覆盖execute、download、download_and_extract、file、os、symlink、template、which、extract、read、delete、patch、rename以及 wasm 相关事件。

例如ExecuteEvent会记录命令行参数（arguments，首项为命令本身）、超时秒数（timeout_seconds）、执行时的环境变量集合（environment）、是否安静执行（quiet）以及输出目录（output_directory）；DownloadEvent则记录 URL 列表（url，多 URL 视为镜像）、输出文件（output）、sha256与 SRI 格式校验和（integrity）。这些字段为逐条审查提供了精确的审计信息。

完整排查流程：从生成日志到定位问题规则

第一步：清空缓存，强制重新初始化

bazel clean --expunge

该命令会清空本地缓存及所有已缓存的仓库，确保所有初始化步骤都会被重新执行，日志才能捕获到完整的初始化过程。

第二步：带上 flag 重新构建

bazel build --experimental_workspace_rules_log_file=/tmp/workspacelog //...

构建完成后，/tmp/workspacelog中会生成一个二进制 proto 文件，包含一系列WorkspaceEvent消息。

第三步：构建并运行 workspacelog 解析器

解析器位于当前仓库的 src/tools/workspacelog 目录，其入口为 WorkspaceLogParser.java，BUILD 目标定义见 BUILD（java_binary，main_class 为com.google.devtools.build.workspacelog.WorkspaceLogParser）。解析器的使用说明参见 README.md。

bazel build src/tools/workspacelog:parser bazel-bin/src/tools/workspacelog/parser --log_path=/tmp/workspacelog > /tmp/workspacelog.txt

该命令将整个 workspace 日志转换为文本输出到 stdout（此处重定向到/tmp/workspacelog.txt）。解析器支持三个选项（定义于 WorkspaceLogParserOptions.java）：

若希望直接写入文件而非 stdout，可使用--output_path：

bazel-bin/src/tools/workspacelog/parser --log_path=/tmp/workspacelog \ --output_path=/tmp/workspacelog.txt

从源码看，解析器通过ExcludingLogParser逐条读取WorkspaceEvent（parseDelimitedFrom），并依据context字段判断是否属于被排除的规则；若命中--exclude_rule指定的规则则跳过。每条事件输出后跟一条由-组成的固定分隔线，便于阅读。

第四步：用 --exclude_rule 过滤内置规则的噪音

原始输出可能非常冗长，包含 Bazel 内置规则产生的大量事件。使用--exclude_rule可以过滤掉特定规则的事件，该选项可以多次指定：

bazel build src/tools/workspacelog:parser bazel-bin/src/tools/workspacelog/parser --log_path=/tmp/workspacelog \ --exclude_rule "//external:local_config_cc" \ --exclude_rule "//external:dep" > /tmp/workspacelog.txt

上述示例会过滤掉由规则//external:local_config_cc和//external:dep产生的所有事件。对应的过滤行为在 WorkspaceLogParserTest.java 中有完整的单元测试覆盖（包括空日志、仅被排除事件、混合事件等场景）。

第五步：打开日志文本，审查不安全操作

打开/tmp/workspacelog.txt，逐条检查被标记为潜在非 hermetic 的操作。每条记录都带有location（来源 .bzl 位置）与context（所属仓库/模块扩展），可直接跳转到对应规则代码进行修复。

六类重点审查的操作及修复要点

日志由WorkspaceEvent消息组成，这些消息概括了对repository_ctx执行的某些潜在非 hermetic 操作。文档明确标记出的高关注操作如下：

execute：在宿主机上执行任意命令

execute会在宿主环境执行任意命令，务必检查这些命令是否引入了对宿主环境的依赖（例如硬编码路径、隐式依赖某个已安装工具等）。这是非 hermetic 行为最直接的来源。

download/download_and_extract：保证指定 sha256

为保证构建的 hermetic 性，下载操作必须指定sha256。未指定校验和的下载意味着内容随远端变化而变化，缓存与可复现性都无法保证。DownloadEvent中sha256与integrity（SRI 格式）字段正是用来审计这一点。

file/template：机制本身无害，但内容来源要查

这两个操作本身并非非 hermetic，但可能是把宿主环境依赖引入仓库的机制。需要确认输入内容的来源，确保其不依赖宿主机环境。TemplateEvent记录的substitutions（替换映射）值得特别留意——若替换值来自宿主机信息，则存在隐患。

os：获取宿主环境特性的便捷通道

os操作本身也不是非 hermetic 的，但它是获取宿主环境依赖的简单途径。一个 hermetic 的构建通常不会调用它。评估时请牢记：它运行在宿主机而非 worker 上，从宿主机获取环境特性（如平台、架构、系统名称）对远程构建通常不是好主意。

symlink：通常安全，但要警惕红旗

symlink通常是安全的，但要寻找红旗信号：

• 指向仓库外部或绝对路径的符号链接会在远端 worker 上引发问题；
• 基于宿主机属性创建的符号链接也大概率有问题。

SymlinkEvent同时记录了链接目标（target）与链接路径（path），便于核对。相关修复建议也可参考远程执行规则适配文档中对repository_ctx.symlink的讨论。

which：检查宿主机程序通常有问题

用which探测宿主机上安装的程序通常是有问题的，因为远端 worker 可能有不同的配置——本地有的程序 worker 上未必有，反之亦然。WhichEvent记录被查找的程序名（program），一旦出现就该考虑改用 toolchain 机制或声明依赖，而不是依赖宿主环境。

从日志到修复：结合仓库证据的落地建议

1. 逐条归类：把日志中的事件按上述六类分组，先处理execute与which（对宿主环境依赖最直接），再处理download缺sha256的项，最后核对file/template/symlink/os的内容来源。
2. 用location定位代码：每条事件都记录了 .bzl 中的精确位置，直接打开对应仓库规则文件修改。
3. 修复后回归验证：再次执行bazel clean --expunge并重新生成日志，确认对应事件消失；同时建议在远端执行配置下跑一遍构建验证。
4. 配套阅读：完整的规则适配方法论见 docs/remote/rules.mdx，其中同样引用了本文所述的 workspace 日志作为定位非 hermetic 行为的工具；仓库规则的机制背景可参考 docs/external/repo.mdx。

小结

workspace 日志机制从 Bazel 0.18 起提供，是一条 flag、一个 proto 格式、一个解析工具的组合，帮助你在远程执行迁移前把 WORKSPACE 规则中的非 hermetic 行为系统性地暴露出来。核心要点可以概括为三条：先bazel clean --expunge保证完整记录；用--exclude_rule过滤内置规则噪音；按execute/download/file+template/os/symlink/which六类逐一审查。工具链的完整实现——从事件定义的 workspace_log.proto、flag 注册的 DebuggingOptions.java，到解析器 WorkspaceLogParser.java 与其测试，都可在当前仓库中直接查看与复用。

【免费下载链接】bazela fast, scalable, multi-language and extensible build system项目地址: https://gitcode.com/GitHub_Trending/ba/bazel