基本用法
terminal
bun CLI 包含一个 Node.js 兼容的包管理器,旨在作为 npm、yarn 和 pnpm 的显著更快的替代品。它是一个独立的工具,可以在现有的 Node.js 项目中使用;如果你的项目已有 package.json,就可以使用 bun install。
⚡️ 快 25 倍 — 在任何 Node.js 项目中从
npm install 切换到 bun install,可以使安装速度提升最多 25 倍。terminal
bun install:
- 安装所有
dependencies、devDependencies和optionalDependencies。Bun 默认也会安装peerDependencies。 - 运行项目的
{pre|post}install和{pre|post}prepare脚本在适当的时间。出于安全原因,Bun 不会执行已安装依赖的生命周期脚本。 - 写入
bun.lock锁文件到项目根目录。
日志
要修改日志详细程度:terminal
生命周期脚本
与其他 npm 客户端不同,Bun 不会为已安装的依赖执行任意生命周期脚本(如postinstall)。执行任意脚本代表潜在的安全风险。
要告诉 Bun 允许特定包的生命周期脚本,请将该包添加到 package.json 的 trustedDependencies 中。
package.json
my-trusted-package 运行生命周期脚本。
生命周期脚本在安装期间并行运行。要调整最大并发脚本数,请使用 --concurrent-scripts 标志。默认值是报告的核心数或 GOMAXPROCS 的两倍。
terminal
esbuild 和 sharp)的 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.json 与 bun.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 注册表应始终提供时间戳)
配置
使用 bunfig.toml 配置 bun install
在 bun install、bun remove 和 bun add 时,Bun 会在以下位置查找 bunfig.toml:
$XDG_CONFIG_HOME/.bunfig.toml或$HOME/.bunfig.toml./bunfig.toml
bunfig.toml 进行配置是可选的。以下是默认值:
bunfig.toml
使用环境变量配置
环境变量优先于bunfig.toml。
Bun 使用目标平台上最快的安装方法:macOS 上的
clonefile 和 Linux 上的 hardlink。你可以使用 --backend 标志更改安装方法。当不可用或出错时,clonefile 和 hardlink 会回退到特定于平台的复制文件实现。
Bun 将从 npm 安装的包存储在 ~/.bun/install/cache/${name}@${version} 中。如果 semver 版本有 build 或 pre 标签,Bun 会用该值的哈希替换它。这减少了长文件路径导致的错误几率,但使得确定包在磁盘上安装的位置变得复杂。
当 node_modules 文件夹存在时,Bun 通过检查预期 node_modules 位置中的 package.json 的 "name" 和 "version" 是否与预期的名称和版本匹配,来决定是否安装包。它使用自定义 JSON 解析器,一旦找到 "name" 和 "version" 就停止解析。
当 bun.lock 不存在或 package.json 的依赖发生变化时,Bun 在解析时会急切地下载和提取 tarball。
当 bun.lock 存在且 package.json 没有变化时,Bun 会延迟下载缺少的依赖。如果具有匹配 name 和 version 的包已经存在于 node_modules 中的预期位置,Bun 将不会尝试下载 tarball。
CI/CD
使用官方的oven-sh/setup-bun 操作在 GitHub Actions 流水线中安装 bun:
.github/workflows/release.yml
bun ci,如果 package.json 与锁文件不同步,构建会失败:
terminal
bun ci 等效于 bun install --frozen-lockfile。它安装 bun.lock 中的精确版本,如果 package.json 与锁文件不匹配则失败。要使用 bun ci 或 bun install --frozen-lockfile,你必须将 bun.lock 提交到版本控制。
在你的工作流中,使用 bun ci 代替 bun install:
.github/workflows/release.yml
特定平台的依赖?
Bun 将 npm 标准化的cpu 和 os 值以及已解析的包一起存储在锁文件中。它会在运行时跳过针对当前目标禁用的包的下载、提取和安装。这意味着即使最终安装的包不同,锁文件在不同平台/架构之间也不会改变。
--cpu 和 --os 标志
你可以覆盖包选择的平台:
--cpu 接受的值:arm、arm64、ia32、mips、mipsel、ppc、ppc64、s390、s390x、x32、x64
--os 接受的值:aix、darwin、freebsd、linux、openbsd、sunos、win32、android
对等依赖?
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_dir 与 clonefile 类似,但每个目录单独克隆每个文件。仅在 macOS 上可用,通常比 clonefile 慢。与 clonefile 不同,这不会在一个系统调用中递归克隆子目录。
copyfile 是上述方法失败时使用的回退方案,也是最慢的。在 macOS 上使用 fcopyfile();在 Linux 上使用 copy_file_range()。
symlink 通常只在内部用于 file: 依赖(以及将来的 link:)。为防止无限循环,会跳过符号链接 node_modules 文件夹。
如果使用 --backend=symlink 安装,Node.js 将无法解析依赖的 node_modules,除非每个依赖都有自己的 node_modules 文件夹,或者你向 node 或 bun 传递 --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
package.json 的 workspaces 字段中:
package.json
目录依赖
使用 pnpm 的catalog: 协议的依赖会被保留:
package.json
配置迁移
Bun 会从pnpm-lock.yaml 和 pnpm-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.yaml 和 pnpm-workspace.yaml 文件。
CLI 用法
terminal
通用配置
string
指定配置文件路径(bunfig.toml)
string
设置特定的当前工作目录
依赖范围与管理
boolean
不安装 devDependencies
boolean
不更新 package.json 或不保存 lockfile
boolean
default:"true"
保存到 package.json
string
从安装中排除 ‘dev’、‘optional’ 或 ‘peer’ 依赖
boolean
仅当依赖尚不存在时才添加到 package.json
依赖类型与版本管理
boolean
将依赖添加到 “devDependencies”
boolean
将依赖添加到 “optionalDependencies”
boolean
将依赖添加到 “peerDependencies”
boolean
添加精确版本而非 ^ 范围
Lockfile 控制
boolean
写入 yarn.lock 文件(yarn v1)
boolean
禁止更改 lockfile
boolean
保存基于文本的 lockfile
boolean
仅生成 lockfile,不安装依赖
网络与注册表设置
string
提供证书颁发机构签名证书
string
证书颁发机构签名证书的文件路径
string
使用特定注册表,覆盖 .npmrc、bunfig.toml 和环境变量
安装流程控制
boolean
不实际安装任何内容
boolean
始终从注册表请求最新版本并重新安装所有依赖
boolean
全局安装
string
特定平台优化:“clonefile”、“hardlink”、“symlink”、“copyfile”
string
为匹配的工作区安装包
boolean
递归分析和安装作为参数传入文件的所有依赖
缓存选项
string
从特定目录路径存储和加载缓存数据
boolean
完全忽略清单缓存
输出与日志
boolean
不输出任何日志
boolean
极度详细的日志输出
boolean
禁用进度条
boolean
不打印摘要
安全与完整性
boolean
跳过验证新下载包的完整性
boolean
添加到项目的 package.json 中的 trustedDependencies 并安装该包
并发与性能
number
生命周期脚本的最大并发作业数(默认:2 倍 CPU 核心数)
number
default:"48"
最大并发网络请求数
生命周期脚本管理
boolean
跳过项目 package.json 中的生命周期脚本(依赖的脚本从不运行)
帮助信息
boolean
打印此帮助菜单