基本用法
terminal
bun CLI 包含一个兼容 Node.js 的包管理器,旨在以显著更快的速度替代 npm、yarn 和 pnpm。它是一个独立工具,可在现有的 Node.js 项目中运行;如果你的项目中有 package.json,就可以使用 bun install。
⚡️ 速度提升 25 倍 — 在任何 Node.js 项目中从 
npm install 切换到 bun install,安装速度可提升高达 25 倍。
针对 Linux 用户
针对 Linux 用户
建议使用的最低 Linux 内核版本是 5.6。如果你使用的是 Linux 内核 5.1 到 5.5,
bun install 能工作,但 HTTP 请求会较慢,因为缺少对 io_uring 的 connect() 操作支持。如果你使用的是 Ubuntu 20.04,可以通过以下方式安装新版内核:terminal
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 标志。默认值为报告的 CPU 数量的两倍或 GOMAXPROCS。
terminal
esbuild 和 sharp)的 postinstall 脚本,确定哪些脚本需要运行。要禁用这些优化:
terminal
工作区(Workspaces)
Bun 支持 package.json 中的"workspaces"。请参阅工作区。
package.json
为特定包安装依赖
在 monorepo 中,可以通过--filter 参数针对部分包安装依赖。
terminal
覆盖与解析
Bun 支持package.json 中 npm 的 "overrides" 和 Yarn 的 "resolutions"。两者都为_元依赖_(即你的依赖项的依赖项)指定版本范围。请参阅覆盖与解析。
package.json
全局安装包
要全局安装包,请使用-g/--global 标志。使用它来安装命令行工具。
terminal
生产模式
要以生产模式安装(不包含devDependencies):
terminal
--production 意味着启用 --frozen-lockfile。它只控制实际安装的内容——早期安装时已经存在于 node_modules 中的 devDependencies 会保留在那里。使用 bun prune --production 将其移除。
如需可复现安装,请使用 --frozen-lockfile。Bun 会安装锁文件中指定的确切版本,并且不会更新锁文件。如果你的 package.json 与 bun.lock 不一致,Bun 会以错误退出。
terminal
--frozen-lockfile;请传入该标志或使用 bun ci。如果完全不存在锁文件,--frozen-lockfile 会从 package.json 安装,但不会写入锁文件。
--frozen-lockfile 支持在经过裁剪的 monorepo 检出目录上运行(例如 turbo prune 的输出,或仅复制了部分工作区文件夹的 Docker 上下文)。bun.lock 中列出但磁盘上缺少其 package.json 的工作区会被跳过,并显示 note:;这些工作区的专属依赖不会被安装。如果剩余的某个工作区依赖于被跳过的工作区,安装将失败。
如需在不安装的情况下验证锁文件,请使用 bun install --frozen-lockfile --dry-run。
有关 bun.lock 的更多信息,请参阅锁文件。
省略依赖
若要省略开发、对等或可选依赖,请使用--omit 标志。
terminal
演练模式
要执行演练而不安装任何内容:terminal
非 npm 依赖
Bun 支持从 Git、GitHub 以及本地或远程托管的 tarball 安装依赖。请参阅bun add。
package.json
安装策略
Bun 支持两种包安装策略,决定依赖如何组织在node_modules 中:
扁平安装(Hoisted installs)
传统 npm/Yarn 方式,将依赖扁平化合并到共享的node_modules 目录:
terminal
隔离安装(Isolated installs)
一种类似 pnpm 的方式,可创建严格的依赖隔离,以防止幻影依赖,即那些可以在未于package.json 中声明的情况下被导入的包:
terminal
node_modules/.bun/ 创建中央包存储,并在顶层 node_modules 中使用符号链接,确保包只能访问声明的依赖。
默认策略
默认链接器策略依据是否是新项目或已有项目:- 新工作区/monorepo:
isolated(防止幻影依赖) - 新单包项目:
hoisted(传统 npm 行为) - 旧项目(v1.3.2 之前创建):
hoisted(保留向后兼容)
configVersion 字段控制。有关详细说明,请参阅隔离安装。
最小发布年龄
为防范恶意软件包被快速发布所导致的供应链攻击,你可以为 npm 软件包配置最低发布时间要求。Bun 会在安装过程中筛除发布时间距今少于指定阈值(以秒为单位)的软件包版本。terminal
bunfig.toml 配置:
bunfig.toml
- 它只会影响新的软件包解析;
bun.lock中已有的软件包保持不变 - 解析时,所有依赖项(直接依赖和传递依赖)都会经过过滤,以满足年龄要求
- 当版本被年龄门槛阻止时,稳定性检查会检测快速修复问题的发布模式
- 如果有多个版本在年龄门槛之外相近时间发布,Bun 会扩展过滤范围,跳过这些可能不稳定的版本,并选择更早发布、更成熟的版本
- 该检查最多会搜索年龄门槛之后的 7 天;如果在此之后发布仍然很频繁,Bun 会忽略稳定性检查
- 精确版本请求(如
[email protected])仍会遵守年龄门槛,但会绕过稳定性检查
- 没有
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
通过环境变量配置
环境变量的优先级高于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" 是否与预期的软件包名称和版本匹配,来决定是否安装软件包。Bun 使用自定义 JSON 解析器,在找到 "name" 和 "version" 后就会停止解析。
当不存在 bun.lock,或者 package.json 中的软件包依赖发生变化时,Bun 会在解析过程中立即下载并提取 tarball。
当存在 bun.lock 且 package.json 未发生变化时,Bun 会延迟下载缺失的依赖。如果 node_modules 中预期位置已经存在名称和版本匹配的软件包,Bun 就不会尝试下载 tarball。
CI/CD
在 GitHub Actions 中使用官方oven-sh/setup-bun 动作安装 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 默认后端,基准测试显示其性能最佳。
clonefile 是 macOS 默认后端,性能最好,仅 macOS 可用。
clonefile_each_dir 类似 clonefile,但每个目录逐文件克隆。仅 macOS 可用,通常性能不及 clonefile。不支持一次系统调用递归克隆子目录。
copyfile 是上述后端失败时使用的回退方案,速度最慢。在 macOS 上,它使用 fcopyfile();在 Linux 上,它使用 copy_file_range()。
symlink 通常仅用于内部 file: 依赖(以及未来的 link:)。为防止循环链接,不会对 node_modules 文件夹做符号链接。
若用 --backend=symlink 安装,除非每个依赖都有自己的 node_modules,否则 Node.js 不会正确解析依赖的 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(锁文件版本 7–9,包括 pnpm 11 的多文档文件)转换为bun.lock - 保留已解析的版本和完整性哈希
- 保留对等依赖范围和
peerDependenciesMeta,因此下一次bun install不会更改迁移后的锁文件 - 迁移 git、GitHub、tarball URL、
file:和npm:别名依赖,包括传递依赖 - 通过
pnpm-workspace.yaml中的namedRegistries解析 pnpm 命名注册表(name@registry:version) - 将注入的工作区包(
dependenciesMeta.*.injected)转换为普通工作区依赖 - 处理已修补的依赖,将 pnpm 仅包含哈希的
patchedDependencies条目与补丁文件进行匹配 - 跳过
runtime:条目(由 pnpm 管理的 Node.js 版本),并显示警告
工作区配置
检测到pnpm-workspace.yaml 时,将工作区配置迁移至根 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 - patchedDependencies 从
pnpm.patchedDependencies迁移至package.json根级patchedDependencies - workspace overrides 应用自
pnpm-workspace.yaml至根package.json
要求和限制
- 要求 pnpm 锁文件版本为 7 或更高
- 工作区包的
package.json中必须包含name字段 - 依赖引用的所有 catalog 条目都必须存在于 catalogs 定义中
pnpm-lock.yaml中的每个工作区都必须在磁盘上有对应的package.json(在 Docker 中,请在运行bun install之前将其复制进去)- 不支持相对路径的
link:依赖,以及带有子目录(resolution.path)的 git 依赖 - 如果迁移因上述任一原因失败,Bun 会打印原因,并改为从头开始解析
pnpm-lock.yaml 和 pnpm-workspace.yaml。
CLI 用法
terminal
通用配置
string
指定配置文件路径(bunfig.toml)
string
设置特定的当前工作目录
依赖范围与管理
boolean
不安装 devDependencies
boolean
不更新 package.json 也不保存锁文件
boolean
default:"true"
保存到 package.json
string
从安装中排除 ‘dev’、‘optional’ 或 ‘peer’ 依赖
boolean
仅当依赖不存在于 package.json 中时才添加
依赖类型与版本控制
boolean
添加依赖到 “devDependencies”
boolean
添加依赖到 “optionalDependencies”
boolean
添加依赖到 “peerDependencies”
boolean
添加确切版本,而不是使用 ^ 范围
锁文件控制
boolean
写入 yarn.lock 文件(yarn v1)
boolean
不允许修改锁文件
boolean
保存基于文本的锁文件
boolean
仅生成锁文件,不安装依赖
网络与注册表设置
string
提供证书颁发机构(CA)签名证书
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
生命周期脚本的最大并发任务数(默认:CPU 核心数的 2 倍)
number
default:"48"
最大并发网络请求数
生命周期脚本管理
boolean
跳过项目 package.json 中的生命周期脚本(依赖的脚本不会被执行)
帮助信息
boolean
打印此帮助菜单