Skip to main content

基本用法

terminal
bun CLI 包含一个 Node.js 兼容的包管理器,旨在作为 npmyarnpnpm 的显著更快的替代品。它是一个独立的工具,可以在现有的 Node.js 项目中使用;如果你的项目已有 package.json,就可以使用 bun install
⚡️ 快 25 倍 — 在任何 Node.js 项目中从 npm install 切换到 bun install,可以使安装速度提升最多 25 倍。
Bun 安装速度对比
要安装项目的所有依赖:
terminal
bun install
  • 安装所有 dependenciesdevDependenciesoptionalDependencies。Bun 默认也会安装 peerDependencies
  • 运行项目的 {pre|post}install{pre|post}prepare 脚本在适当的时间。出于安全原因,Bun 不会执行已安装依赖的生命周期脚本。
  • 写入 bun.lock 锁文件到项目根目录。

日志

要修改日志详细程度:
terminal

生命周期脚本

与其他 npm 客户端不同,Bun 不会为已安装的依赖执行任意生命周期脚本(如 postinstall)。执行任意脚本代表潜在的安全风险。 要告诉 Bun 允许特定包的生命周期脚本,请将该包添加到 package.jsontrustedDependencies 中。
package.json
然后重新安装该包。Bun 会读取此字段并为 my-trusted-package 运行生命周期脚本。 生命周期脚本在安装期间并行运行。要调整最大并发脚本数,请使用 --concurrent-scripts 标志。默认值是报告的核心数或 GOMAXPROCS 的两倍。
terminal
Bun 会自动优化流行包(如 esbuildsharp)的 postinstall 脚本,通过确定哪些脚本需要运行。要禁用这些优化:
terminal

工作空间

Bun 支持 package.json 中的 "workspaces"。请参阅工作空间
package.json

为特定包安装依赖

在单体仓库中,你可以使用 --filter 标志为一部分包安装依赖。
terminal
请参阅过滤

Overrides 和 Resolutions

Bun 支持 package.json 中的 npm "overrides" 和 Yarn "resolutions"。两者都用于指定_元依赖_(即你依赖的依赖)的版本范围。请参阅overrides 和 resolutions
package.json

全局包

要全局安装一个包,请使用 -g/--global 标志。用于安装命令行工具。
terminal

生产模式

要以生产模式安装(不包含 devDependencies):
terminal
对于可重现的安装,请使用 --frozen-lockfile。Bun 会安装锁文件中指定的确切版本,并且不会更新它。如果你的 package.jsonbun.lock 不一致,Bun 会退出并报错。
terminal
请参阅锁文件了解更多关于 bun.lock 的信息。

省略依赖

要省略开发、对等或可选依赖,请使用 --omit 标志。
terminal

空运行

执行空运行,不实际安装任何东西:
terminal

非 npm 依赖

Bun 支持从 Git、GitHub 以及本地或远程托管的 tarball 安装依赖。请参阅 bun add
package.json

安装策略

Bun 支持两种决定依赖在 node_modules 中组织方式的包安装策略:

提升安装

传统的 npm/Yarn 方法,将依赖扁平化到共享的 node_modules 目录中:
terminal

隔离安装

一种类似 pnpm 的方法,创建严格的依赖隔离以防止幽灵依赖——那些可以在未在 package.json 中声明的情况下导入的包:
terminal
隔离安装在 node_modules/.bun/ 中创建中央包存储,并在顶层 node_modules 中创建符号链接。这确保了包只能访问其声明的依赖。

默认策略

默认链接器策略取决于你是新项目还是已有现有项目:
  • 新的工作空间/单体仓库: isolated(防止幽灵依赖)
  • 新的单包项目: hoisted(传统的 npm 行为)
  • 现有项目(v1.3.2 之前创建): hoisted(保持向后兼容性)
默认值由锁文件中的 configVersion 字段控制。详细说明请参阅隔离安装

最小发布年龄

为了防止恶意包快速发布的供应链攻击,你可以为 npm 包配置最小年龄要求。Bun 会在安装期间过滤掉发布时间距离现在小于指定阈值(以秒为单位)的包版本。
terminal
你也可以在 bunfig.toml 中配置:
bunfig.toml
当最小年龄过滤器激活时:
  • 它仅影响新的包解析;bun.lock 中的现有包保持不变
  • 所有依赖(直接和传递)在解析时都会被过滤以满足年龄要求
  • 当版本被年龄门控阻止时,稳定性检查会检测快速的 bug 修复模式
    • 如果在你的年龄门控之外有多个版本在短期内相继发布,Bun 会扩展过滤器以跳过这些可能不稳定的版本,并选择一个更旧、更成熟的版本
    • 该检查会在年龄门控之后最多搜索 7 天;如果在此之后仍有快速发布,Bun 会忽略稳定性检查
    • 精确版本请求(如 package@1.1.1)仍然遵循年龄门控但绕过稳定性检查
  • 没有 time 字段的版本被视为通过年龄检查(npm 注册表应始终提供时间戳)
有关更高级的安全扫描,包括与服务的集成和自定义过滤,请参阅安全扫描器 API

配置

使用 bunfig.toml 配置 bun install

bun installbun removebun add 时,Bun 会在以下位置查找 bunfig.toml
  1. $XDG_CONFIG_HOME/.bunfig.toml$HOME/.bunfig.toml
  2. ./bunfig.toml
如果两者都存在,结果会合并在一起。 使用 bunfig.toml 进行配置是可选的。以下是默认值:
bunfig.toml

使用环境变量配置

环境变量优先于 bunfig.toml Bun 使用目标平台上最快的安装方法:macOS 上的 clonefile 和 Linux 上的 hardlink。你可以使用 --backend 标志更改安装方法。当不可用或出错时,clonefilehardlink 会回退到特定于平台的复制文件实现。 Bun 将从 npm 安装的包存储在 ~/.bun/install/cache/${name}@${version} 中。如果 semver 版本有 buildpre 标签,Bun 会用该值的哈希替换它。这减少了长文件路径导致的错误几率,但使得确定包在磁盘上安装的位置变得复杂。 node_modules 文件夹存在时,Bun 通过检查预期 node_modules 位置中的 package.json"name""version" 是否与预期的名称和版本匹配,来决定是否安装包。它使用自定义 JSON 解析器,一旦找到 "name""version" 就停止解析。 bun.lock 不存在或 package.json 的依赖发生变化时,Bun 在解析时会急切地下载和提取 tarball。 bun.lock 存在且 package.json 没有变化时,Bun 会延迟下载缺少的依赖。如果具有匹配 nameversion 的包已经存在于 node_modules 中的预期位置,Bun 将不会尝试下载 tarball。

CI/CD

使用官方的 oven-sh/setup-bun 操作在 GitHub Actions 流水线中安装 bun
.github/workflows/release.yml
对于想要强制可重现构建的 CI/CD 环境,请使用 bun ci,如果 package.json 与锁文件不同步,构建会失败:
terminal
bun ci 等效于 bun install --frozen-lockfile。它安装 bun.lock 中的精确版本,如果 package.json 与锁文件不匹配则失败。要使用 bun cibun install --frozen-lockfile,你必须将 bun.lock 提交到版本控制。 在你的工作流中,使用 bun ci 代替 bun install
.github/workflows/release.yml

特定平台的依赖?

Bun 将 npm 标准化的 cpuos 值以及已解析的包一起存储在锁文件中。它会在运行时跳过针对当前目标禁用的包的下载、提取和安装。这意味着即使最终安装的包不同,锁文件在不同平台/架构之间也不会改变。

--cpu--os 标志

你可以覆盖包选择的平台:
这些标志会为指定平台安装包,而不是当前系统。用于跨平台构建或为不同环境准备部署时使用。 --cpu 接受的值armarm64ia32mipsmipselppcppc64s390s390xx32x64 --os 接受的值aixdarwinfreebsdlinuxopenbsdsunoswin32android

对等依赖?

Bun 处理对等依赖的方式与 Yarn 类似:bun install 会自动安装它们。如果依赖在 peerDependenciesMeta 中被标记为可选,Bun 会尽可能使用现有的依赖。

锁文件

bun.lock 是 Bun 的锁文件格式。请参阅我们关于文本锁文件的博客文章 在 Bun 1.2 之前,锁文件是二进制的,称为 bun.lockb。要将旧锁文件升级为新格式,请运行 bun install --save-text-lockfile --frozen-lockfile --lockfile-only,然后删除 bun.lockb

缓存

要删除缓存:

特定平台的后端

为了性能,bun install 根据平台使用不同的系统调用来安装依赖。你可以使用 --backend 标志强制使用特定的后端。 hardlink 是 Linux 上的默认后端。基准测试表明它是 Linux 上最快的。
clonefile 是 macOS 上的默认后端。基准测试表明它是 macOS 上最快的。仅在 macOS 上可用。
clonefile_each_dirclonefile 类似,但每个目录单独克隆每个文件。仅在 macOS 上可用,通常比 clonefile 慢。与 clonefile 不同,这不会在一个系统调用中递归克隆子目录。
copyfile 是上述方法失败时使用的回退方案,也是最慢的。在 macOS 上使用 fcopyfile();在 Linux 上使用 copy_file_range()
symlink 通常只在内部用于 file: 依赖(以及将来的 link:)。为防止无限循环,会跳过符号链接 node_modules 文件夹。 如果使用 --backend=symlink 安装,Node.js 将无法解析依赖的 node_modules,除非每个依赖都有自己的 node_modules 文件夹,或者你向 nodebun 传递 --preserve-symlinks。请参阅 Node.js 关于 --preserve-symlinks 的文档

npm 注册表元数据

Bun 使用二进制格式缓存 npm 注册表响应。这比 JSON 加载快得多,且磁盘占用通常更小。 这些文件位于 ~/.bun/install/cache/*.npm。文件名模式是 ${hash(packageName)}.npm。使用哈希是为了避免为作用域包创建额外的目录。 Bun 对 Cache-Control 的使用会忽略 Age。这提高了性能,但意味着 Bun 可能比 npm 最新包版本元数据晚大约 5 分钟。

pnpm 迁移

Bun 会自动从 pnpm 迁移项目。当检测到 pnpm-lock.yaml 文件且没有 bun.lock 文件时,Bun 会在安装期间将锁文件转换为 bun.lock。原始的 pnpm-lock.yaml 文件保持不变。
terminal
迁移仅在 bun.lock 不存在时运行。目前没有 pnpm 迁移的退出标志。 迁移过程处理:

锁文件迁移

  • pnpm-lock.yaml 转换为 bun.lock 格式
  • 保留包版本和解析信息
  • 维护依赖关系和对等依赖
  • 处理带有完整性哈希的修补依赖

工作空间配置

当存在 pnpm-workspace.yaml 文件时,Bun 会将工作空间设置迁移到你的根 package.json
pnpm-workspace.yaml
Bun 将工作空间包列表和目录移动到 package.jsonworkspaces 字段中:
package.json

目录依赖

使用 pnpm 的 catalog: 协议的依赖会被保留:
package.json

配置迁移

Bun 会从 pnpm-lock.yamlpnpm-workspace.yaml 迁移以下 pnpm 配置:
  • Overrides:从 pnpm.overrides 移动到 package.json 的根级 overrides
  • 修补的依赖:从 pnpm.patchedDependencies 移动到 package.json 的根级 patchedDependencies
  • 工作空间 Overrides:从 pnpm-workspace.yaml 应用到根 package.json

要求

  • 需要 pnpm 锁文件版本 7 或更高
  • 工作空间包必须在其 package.json 中有 name 字段
  • 依赖引用的所有目录条目必须存在于目录定义中
迁移后,你可以安全地删除 pnpm-lock.yamlpnpm-workspace.yaml 文件。

CLI 用法

terminal

通用配置

--config
string
指定配置文件路径(bunfig.toml)
--cwd
string
设置特定的当前工作目录

依赖范围与管理

--production
boolean
不安装 devDependencies
--no-save
boolean
不更新 package.json 或不保存 lockfile
--save
boolean
default:"true"
保存到 package.json
--omit
string
从安装中排除 ‘dev’、‘optional’ 或 ‘peer’ 依赖
--only-missing
boolean
仅当依赖尚不存在时才添加到 package.json

依赖类型与版本管理

--dev
boolean
将依赖添加到 “devDependencies”
--optional
boolean
将依赖添加到 “optionalDependencies”
--peer
boolean
将依赖添加到 “peerDependencies”
--exact
boolean
添加精确版本而非 ^ 范围

Lockfile 控制

--yarn
boolean
写入 yarn.lock 文件(yarn v1)
--frozen-lockfile
boolean
禁止更改 lockfile
--save-text-lockfile
boolean
保存基于文本的 lockfile
--lockfile-only
boolean
仅生成 lockfile,不安装依赖

网络与注册表设置

--ca
string
提供证书颁发机构签名证书
--cafile
string
证书颁发机构签名证书的文件路径
--registry
string
使用特定注册表,覆盖 .npmrc、bunfig.toml 和环境变量

安装流程控制

--dry-run
boolean
不实际安装任何内容
--force
boolean
始终从注册表请求最新版本并重新安装所有依赖
--global
boolean
全局安装
--backend
string
特定平台优化:“clonefile”、“hardlink”、“symlink”、“copyfile”
--filter
string
为匹配的工作区安装包
--analyze
boolean
递归分析和安装作为参数传入文件的所有依赖

缓存选项

--cache-dir
string
从特定目录路径存储和加载缓存数据
--no-cache
boolean
完全忽略清单缓存

输出与日志

--silent
boolean
不输出任何日志
--verbose
boolean
极度详细的日志输出
--no-progress
boolean
禁用进度条
--no-summary
boolean
不打印摘要

安全与完整性

--no-verify
boolean
跳过验证新下载包的完整性
--trust
boolean
添加到项目的 package.json 中的 trustedDependencies 并安装该包

并发与性能

--concurrent-scripts
number
生命周期脚本的最大并发作业数(默认:2 倍 CPU 核心数)
--network-concurrency
number
default:"48"
最大并发网络请求数

生命周期脚本管理

--ignore-scripts
boolean
跳过项目 package.json 中的生命周期脚本(依赖的脚本从不运行)

帮助信息

--help
boolean
打印此帮助菜单