基本用法
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
通用配置
指定配置文件路径(bunfig.toml)
设置特定的当前工作目录
依赖范围与管理
不安装 devDependencies
不更新 package.json 或不保存 lockfile
保存到 package.json
从安装中排除 ‘dev’、‘optional’ 或 ‘peer’ 依赖
仅当依赖尚不存在时才添加到 package.json
依赖类型与版本管理
将依赖添加到 “devDependencies”
将依赖添加到 “optionalDependencies”
将依赖添加到 “peerDependencies”
添加精确版本而非 ^ 范围
Lockfile 控制
写入 yarn.lock 文件(yarn v1)
禁止更改 lockfile
保存基于文本的 lockfile
仅生成 lockfile,不安装依赖
网络与注册表设置
提供证书颁发机构签名证书
证书颁发机构签名证书的文件路径
使用特定注册表,覆盖 .npmrc、bunfig.toml 和环境变量
安装流程控制
不实际安装任何内容
始终从注册表请求最新版本并重新安装所有依赖
全局安装
特定平台优化:“clonefile”、“hardlink”、“symlink”、“copyfile”
为匹配的工作区安装包
递归分析和安装作为参数传入文件的所有依赖
缓存选项
从特定目录路径存储和加载缓存数据
完全忽略清单缓存
输出与日志
不输出任何日志
极度详细的日志输出
禁用进度条
不打印摘要
安全与完整性
跳过验证新下载包的完整性
添加到项目的 package.json 中的 trustedDependencies 并安装该包
并发与性能
生命周期脚本的最大并发作业数(默认:2 倍 CPU 核心数)
最大并发网络请求数
生命周期脚本管理
跳过项目 package.json 中的生命周期脚本(依赖的脚本从不运行)
帮助信息
打印此帮助菜单