# @bazel/bazelisk 中文文档 规范地址：https://npmcn.com/package/%40bazel/bazelisk/ 版本：1\.28\.1 npm 元数据更新时间：2026-01-19T16:48:27.804Z 中文译文更新时间：2026-11-07T18:36:37.091Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bazel/bazelisk 原文对照：https://npmcn.com/package/%40bazel/bazelisk/?lang=original 项目主页：https://github.com/bazelbuild/bazelisk#readme 源码仓库：https://github.com/bazelbuild/bazelisk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：44.9 MB，11 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - 首次发布：2020-02-04T19:31:55.064Z - 最新版本发布：2026-01-19T16:48:27.628Z - 近 30 天下载量：347931（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：30（近 12 个月 2 个） ## 中文简介 Bazel 方便用户的启动器 ## 安装 ```sh npm install @bazel/bazelisk ``` 也可以使用：`pnpm add @bazel/bazelisk`、`yarn add @bazel/bazelisk`、`bun add @bazel/bazelisk` ## README # 巴泽利斯克语Name **巴泽尔的方便用户的发射装置.** ## 关于巴泽利斯克 巴泽利斯克是巴泽尔用Go写作的包装纸. 它会自动从您当前工作目录中选择Bazel的好版本,从官方服务器下载(如果需要),然后透明地通过所有命令行参数到真正的Bazel 二进制. 你可以叫它 就像你会叫巴泽尔. ## 安装 在macOS上: `brew install bazelisk`。 。 。 . 在视窗上 : `winget install Bazel.Bazelisk`, (中文(简体) ), `choco install bazelisk`,或 `scoop install bazelisk`。 。 。 . 每一个都增加了白蜡 `PATH` 作为两者 `bazelisk` 财务报告和审定财务报表 `bazel`。 。 。 . 在 Linux 上: 您可以下载 Bazelisk 二进制 [释放](https://github.com/bazelbuild/bazelisk/releases) 页面并添加到您的 `PATH` 手动操作,它也在macOS和Windows上工作. 巴泽利斯克语也发布于npm. 前端开发者可能想要用 `npm install -g @bazel/bazelisk`。 。 。 . > 你会注意到,对于巴泽尔来说,它具有类似的作用 [`nvm` 工具](https://github.com/nvm-sh/nvm) 管理您版本的节点. 在 Linux/ macOS 上,您也可以 [爱](https://github.com/jdx/mise) 类似命令的多块工具版本管理器 `mise use -g bazelisk@latest` 一些如何使用它的想法: - 装作 `bazel` 二进制 `PATH` (例如抄送 `/usr/local/bin/bazel`) (中文(简体) ). 不要再担心将Bazel升级到最新版本. - 检查到您的仓库,并建议用户通过 `./bazelisk build //my:software`。 。 。 . 这样,即使是从未使用过Bazel或者没有安装过它的人,也可以建立你的软件. - 作为使用Bazel或作为项目所有人的公司,增加: `.bazelversion` 文档到您的仓库. 这将让 Bazelisk 在您的工作空间运行时使用文件中指定的精确版本 . 它的版本在你的存储器中 将允许Bazel的原子升级 包括所有必要的修改. 如果你将巴泽利斯克安装为 `bazel` 也可以通过正常的预投/拉请求测试 Bazel 升级. 这也将确保用户不会试图用不相容的"Bazel"版本来构建您的项目,这常常是导致挫折和失败的构建的原因. (但见下文关于确保您的开发者安装 Bazelisk 的说明 。) 在"戈"中巴泽利斯克被重写之前,它是一个Python剧本. 这仍然有效,并具有在任何拥有Python解译器的平台上运行的优势,但目前还没有维护,并且没有支持同样多的特性. 以下文件仅介绍较新的Go版本. ## 巴泽利斯克怎么知道哪一个巴泽尔版本要运行? 它使用简单的算法: - 如果环境变量 `USE_BAZEL_VERSION` ,它将使用在数值中指定的版本. - 否则,如果 `.bazeliskrc` 文件存在于工作空间根并包含 `USE_BAZEL_VERSION` 变量,此版本将被使用. - 否则,如果 `.bazelversion` 文件存在于当前目录中或递归到任何父目录中,它将读取该文件并使用其中指定的版本. - 否则,如果环境可变 `USE_BAZEL_FALLBACK_VERSION` 设置为以下格式之一: - 如果设定为起始值 `error:`,它将报告错误,版本检测会失败. - 如果设定为起始值 `warn:`,它将报告警告并使用前缀后指定的版本. - 如果设定为起始值 `silent:`,它将使用前缀后指定的版本. - 否则,它将使用Bazel最新官方发布. 一个版本可以选择前缀有叉名. 分叉和版本应以斜线分隔: `/`。 。 。 . 请参见下一节"如何用叉". Bazelisk目前理解以下版本标签格式: - `latest` 指在GitHub上发布的Bazel的最新稳定(LTS)版本. 先前的释放可通过 `latest-1`, (中文(简体) ), `latest-2` 包括:. - 类似版本编号 `0.17.2` 意思是巴泽尔的准确版本. 也可以是发行候选版本,比如: `0.20.0rc3`,或滚动发布版本,如 `5.0.0-pre.20210317.1`。 。 。 . - 浮式版本标识符像 `4.x` 返回最近一个 **释放** 从"LTS"系列开始由Bazel 4.0.0. - 通配符版本标识符类似 `4.*` 返回最近一个 **释放或候选人** 从"LTS"系列开始由Bazel 4.0.0. - 基特人的一团糟 请注意,Bazel二进制只用于通过 [巴泽尔CI](https://buildkite.com/bazel/bazel-bazel)。 。 。 . 此外,我们只支持官方发布一些特殊版本的名称(这些格式在使用叉时无效): - `last_green` 提到巴泽尔二进制,它是在最近通过的承诺上建造的 [巴泽尔CI](https://buildkite.com/bazel/bazel-bazel)。 。 。 . 这个二进制最理想的应该是非常接近巴泽尔头部. - `last_rc` 说明最近释放的候选人. 如果没有主动释放候选人,巴泽利斯克则使用最新的巴泽尔发行. - `rolling` 指最近的滚动发布(即使有更新的LTS发布). 说明: `last_downstream_green` 支持已被删除, 请使用 `last_green` 换句话说. ## 巴泽利斯克从哪里得到巴泽尔的? Bazelisk从Google Cloud存储器中获取了绿色承诺所建的Bazel 版本, 所下载的文物根据记录的SHA256价值进行验证 `BAZELISK_VERIFY_SHA256` 如果在配置文件中设置了此变量. 如上节所述 `/` 版本格式允许您使用您在 GitHub 上的 Bazel 叉 : 如果你想用你自己的放出建立一个叉子,你应该遵循我们用来命名的常规 `bazelbuild/bazel` 用于二进制文件名,因为这会导致可以预测的URL,类似于官方的URL. URL 格式看起来像 `https://github.com//bazel/releases/download//`。 。 。 . 您也可以通过设置环境变量来覆盖 URL `$BAZELISK_BASE_URL`然后巴泽利斯克将附加 `//` 改为基础 URL,而不是使用正式发布服务器。 巴泽利斯克将读取文件 [`~/.netrc`](https://everything.curl.dev/usingcurl/netrc) 基本认证证书. 如果出于任何原因这些都行不通,您也可以通过设置环境变量来完全覆盖 URL 格式 `$BAZELISK_FORMAT_URL`。该变量使用一个带有占位符的格式式字符串,并进行以下替换以计算下载 URL: - `%e`: 扩展后缀,例如空字符串或 `.exe`。 。 。 . - `%h`数值: `BAZELISK_VERIFY_SHA256`,尊重大写/小写字符. - `%m`: 机器架构名称, 如 `arm64` 或者说 `x86_64`。 。 。 . - `%o`: 操作系统名称, 例如 `darwin` 或者说 `linux`。 。 。 . - `%v`: Bazelisk确定的巴策尔版本. - `%%`: 字义 `%` 为了逃跑. - 后面的所有其他字符 `%` 用于未来使用,并导致处理出错. ## Bazelisk 设定的环境变量 Bazelisk 预置目录到 `PATH` 包含下载的 Bazel 二进制. 这确保了Bazel的目标 `bazel` 将使用与外部引用相同的 Bazel 二进制 . Bazelisk 还设置了环境变量 `BAZELISK` 走向自己的道路. 这对想要知道是否在巴泽利斯克下运行的脚本是有用的,也可以用来从巴泽尔跑内运行特定的巴泽尔版本,例如生成特定版本的测试数据. ## 确保您的开发者使用 Bazelisk 而不是 Bazel 巴泽尔安装器通常提供巴泽尔的 [shell 包装脚本](https://github.com/bazelbuild/bazel/blob/master/scripts/packages/bazel.sh) 作为 `bazel` 在路径. 这样安装时,Bazel检查 `.bazelversion` 文件本身,但当它与实际版本的Bazel不匹配时的失败会给开发者带来相当的混乱. 你可能会发现自己必须解释巴泽尔和巴泽利斯克的区别(特别是当你升级了被绑定的版本时). 为了避免这种情况,你可以在你的支票中添加 `tools/bazel` 包装. 由于巴泽利斯克小心避免在循环中自称,所以它总是用环境变量的包装来称呼自己 `BAZELISK_SKIP_WRAPPER` 设为"真". 您可以检查该变量是否存在, 当找不到时, 向用户报告关于如何安装 Bazelisk 的有用错误 . 注意,如果用户直接下载了Bazel 二进制并放入他们的 PATH,而不是运行 然后是安装器 `tools/bazel` 财务报告和审定财务报表 `.bazelversion` 未检查。 你可以打电话给 [版本。 请检查](https://github.com/bazelbuild/bazel-skylib/blob/1.1.1/docs/versions_doc.md#versionscheck) 从工作端点开始到 用户需要更新其标签. ## 其他特征 Go版"巴泽利斯克"提供三面新旗. ### \--限制 `--strict` 扩展到给定版本的 Bazel 可能启用的不兼容旗帜. ```shell bazelisk --strict build //... ``` ### \--移徙 `--migrate` 将多次运行 Bazel 来帮助您识别兼容性问题 . 如果代码失败 `--strict`,旗帜 `--migrate` 将使用每个旗子分别运行巴泽尔,并在结尾打印出报告. 这将显示哪些旗帜可以安全启用,哪些旗帜需要迁移. ### \--双节 `--bisect` 旗帜允许您使用 Bazel 版本来查找哪个版本引入了构建失败 。 您可以指定二节节的版本范围 `--bisect=..`,其中GOD是最后一个已知的工作Bazel版本,而BAD则是第一个已知的非工作Bazel版本. 巴泽利斯克的使用 [GitHub 比较 API](https://docs.github.com/en/rest/commits/commits#compare-two-commits) 以获得承诺的列表 双虫。 当GOD不是BAD的祖先时,GOD被重置为他们的合并基础承诺. GOOD和BAD的含义可以通过前缀范围来逆转 `~`,比如说. `--bisect=~6.0.0..HEAD` 将发现第一个版本介于 6. 0. 0 和 头部之间 _修补_ 大楼. 实例: ```shell # Bisect between 6.0.0 and Bazel at HEAD to find the first commit that breaks the build. bazelisk --bisect=6.0.0..HEAD test //foo:bar_test # Bisect between 6.1.0 and the second release candidate of Bazel 6.2.0 bazelisk --bisect=6.1.0..release-6.2.0rc2 test //foo:bar_test # Bisect between two commits on the main branch (or branches with `release-` prefix) of the Bazel GitHub repository. bazelisk --bisect=.. test //foo:bar_test # Bisect between 6.0.0 and Bazel at HEAD to find the first commit that *fixes* the build. bazelisk --bisect=~6.0.0..HEAD test //foo:bar_test ``` 请注意,Bazelisk在主干线和放行线上使用预建的 Bazel 二进制,因此不能将本地的收发线分开. ### 命令行补全 巴泽利斯克提供了一个新的 `completion` 命令,允许您生成 用于 Bazel 命令的命令行补全脚本. #### 击打 您可以通过下列两种方式使 Bash 完成: 1. 在 Bazel 工作空间中源代码生成的补全脚本 : ```shell source <(bazelisk completion bash) ``` 2. 或将完成脚本放入文件 : ```shell bazelisk completion bash > bash-complete.bash ``` 然后复制此文件到 `/etc/bash_completion.d` (在Ubuntu上) 或来源于您 `~/.bashrc` (关于Ubuntu)或 `~/.bash_profile` (关于macOS). ```shell source /path/to/bazel-complete.bash ``` #### 鱼 生成完成脚本并保存到您的鱼完成目录中: ```shell bazelisk completion fish > ~/.config/fish/completions/bazel.fish ``` 注意生成的完成脚本被绑定在活性的Bazel版本上. Batzel完成脚本取自安装器二进制. 如果你使用一个 自定义基础 URL, 确保安装者 URL 与 巴泽尔二进制. ### \-- migrate 和 --bipsect 的有用环境变量 你可以设置 `BAZELISK_INCOMPATIBLE_FLAGS` 设置不兼容旗帜列表(由 `,`要测试,否则Bazelisk将首先测试所有旗帜 `--incompatible_`。 。 。 . 你可以设置 `BAZELISK_GITHUB_TOKEN` 设置用于 API 请求的 GitHub 访问令牌,以避免在共享网络上限制费率. 你可以设置 `BAZELISK_SHUTDOWN` 要运行 `shutdown` 在迁移或分割时,如果怀疑会影响结果. 你可以设置 `BAZELISK_CLEAN` 要运行 `clean --expunge` 在迁移或分割时,如果怀疑会影响结果. ## 工具/标签 巴泽利斯克会试着从 `tools` 如果存在目录, 而不是下载的 Bazel 版本 。 环境变量 `BAZEL_REAL`由 Bazelisk 无条件设置,可以被包装器用于执行已下载的 Bazel 二进制. Bazelisk 寻找下列包装,顺序为: - `tools/bazel.-[.exe]`: OS- 和平台专用可执行文件 - `tools/bazel.[.exe]`: 具有平台特性的可执行文件(对于您的项目只支持一个操作系统的情况) - `tools/bazel[.exe]`: 可执行文件或 shell 脚本 - `tools/bazel.ps1`: Windows 上的 PowerShell 脚本 - `tools/bazel.bat`: Windows 上的批次文件 地点 `.exe` 在Windows上需要扩展. 另外,在Windows上 `tools/bazel` 允许以最低优先级。 虽然不推荐,而且可能引起问题,但支持后向相容性. 通过设置环境变量可禁用此行为 `BAZELISK_SKIP_WRAPPER` 至任何值(空字符串除外),然后发射 Bazelisk . 您可以通过设置来控制 Bazelisk 在所有 HTTP 请求中发送的用户代理 `BAZELISK_USER_AGENT` 达到理想价值. # .bazeliskrc 配置文件 A 类 `.bazeliskrc` 在工作区根目录或用户家目录中的文件允许用户持续设置环境变量。 (Bazelisk的 Python 执行还没有检查用户家目录,只有工作空间目录. ) 示例文件内容 : ```shell USE_BAZEL_VERSION=0.19.0 BAZELISK_GITHUB_TOKEN=abc ``` 下列变量可以设置: - `BAZELISK_BASE_URL` - `BAZELISK_FORMAT_URL` - `BAZELISK_NOJDK` - `BAZELISK_CLEAN` - `BAZELISK_GITHUB_TOKEN` - `BAZELISK_HOME_DARWIN` - `BAZELISK_HOME_LINUX` - `BAZELISK_HOME_WINDOWS` - `BAZELISK_HOME` - `BAZELISK_INCOMPATIBLE_FLAGS` - `BAZELISK_SHOW_PROGRESS` - `BAZELISK_SHUTDOWN` - `BAZELISK_SKIP_WRAPPER` - `BAZELISK_USER_AGENT` - `BAZELISK_VERIFY_SHA256` - `USE_BAZEL_VERSION` 对配置变量按优先排序进行评估。 首选值按最高至最低优先排序如下: - 环境定义变量 - 工作空间根定义的变量 `.bazeliskrc` - 用户之家定义的变量 `.bazeliskrc` 此外,Bazelisk家庭目录也按优先顺序加以评估。 首选值是OS特定值等. `BAZELISK_HOME_LINUX`然后我们回到 `BAZELISK_HOME`。 。 。 . ## 所需资源 为方便使用,Python版本的Bazelisk被写成与Python 2.7和3.x合作,只使用由标准库提供的模块. Go版本可以被编译出在Linux,macOS和Windows上本土运行. 要安装, 请运行 : ```shell go install github.com/bazelbuild/bazelisk@latest ``` 把它添加到你的路径: ```shell export PATH=$PATH:$(go env GOPATH)/bin ``` 更多信息,请访问InfoFinland上的 [`GOPATH` 环境变量](https://github.com/golang/go/wiki/SettingGOPATH)。 。 。 . ## 未来的想法 - 添加选中的 Bazel 二进制支持 . - 当版本标签设定为承诺散列时,首先下载一个匹配的二进制版本"Bazel",然后在该承诺时自动构建"Bazel"并使用由此产生的二进制. ## 财务问题 ### 巴泽利斯克将下载的"巴泽尔"版本存放在哪里?? 它在你的内心创建了一个名为"bazelisk"的目录 [用户缓存目录](https://golang.org/pkg/os/#UserCacheDir) 并把它们存放在那里. 请随时删除此目录, 因为需要时可以自动重生成 . ## 常见问题 ### @bazel/bazelisk 是什么？ Bazel 方便用户的启动器 ### 如何安装 @bazel/bazelisk？ 在项目目录运行 npm install @bazel/bazelisk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bazelisk、bazel，可以用 npx bazelisk 直接运行。 ### @bazel/bazelisk 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @bazel/bazelisk 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @bazel/bazelisk 可以商用吗？ @bazel/bazelisk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @bazel/bazelisk 的下载量有多少？ 根据 npm 官方下载统计，@bazel/bazelisk 在 2026/10/08 – 2026/11/06 这 30 天内被下载 347,931 次，日均约 11,598 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @bazel/bazelisk 还在维护吗？ 最新版本 1\.28\.1 发布于 2026/01/20（9 个月前）；至今共发布 30 个版本，其中过去 12 个月发布了 2 个；首次发布于 2020/02/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。