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 安装速度对比
建议使用的最低 Linux 内核版本是 5.6。如果你使用的是 Linux 内核 5.1 到 5.5,bun install 能工作,但 HTTP 请求会较慢,因为缺少对 io_uring 的 connect() 操作支持。如果你使用的是 Ubuntu 20.04,可以通过以下方式安装新版内核:
terminal
安装项目中所有依赖:
terminal
bun install:
  • 安装所有 dependenciesdevDependenciesoptionalDependencies。Bun 默认安装 peerDependencies
  • 运行项目的 {pre|post}install{pre|post}prepare 脚本,并在适当的时间执行。出于安全原因,Bun 不会执行 已安装依赖项的生命周期脚本。
  • 写入一个 bun.lock 锁文件到项目根目录。

日志记录

调整日志详情级别:
terminal

生命周期脚本

与其他 npm 客户端不同,Bun 不会执行安装依赖的任意生命周期脚本(如 postinstall)。执行任意脚本存在潜在安全风险。 若需允许 Bun 针对特定包执行生命周期脚本,请在你的 package.json 中将该包添加到 trustedDependencies 字段。
package.json
然后重新安装该包。Bun 会读取此字段并运行 my-trusted-package 的生命周期脚本。 生命周期脚本会在安装期间并行运行。若要调整并发脚本的最大数量,请使用 --concurrent-scripts 标志。默认值为报告的 CPU 数量的两倍或 GOMAXPROCS。
terminal
Bun 会自动优化热门包(如 esbuildsharp)的 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.jsonbun.lock 不一致,Bun 会以错误退出。
terminal
Bun 不会在 CI 中自动启用 --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 中使用符号链接,确保包只能访问声明的依赖。

默认策略

默认链接器策略依据是否是新项目或已有项目:
  • 新工作区/monorepoisolated(防止幻影依赖)
  • 新单包项目hoisted(传统 npm 行为)
  • 旧项目(v1.3.2 之前创建)hoisted(保留向后兼容)
默认设置由锁文件中的 configVersion 字段控制。有关详细说明,请参阅隔离安装

最小发布年龄

为防范恶意软件包被快速发布所导致的供应链攻击,你可以为 npm 软件包配置最低发布时间要求。Bun 会在安装过程中筛除发布时间距今少于指定阈值(以秒为单位)的软件包版本。
terminal
也可以在 bunfig.toml 配置:
bunfig.toml
启用最小年龄过滤时:
  • 它只会影响新的软件包解析;bun.lock 中已有的软件包保持不变
  • 解析时,所有依赖项(直接依赖和传递依赖)都会经过过滤,以满足年龄要求
  • 当版本被年龄门槛阻止时,稳定性检查会检测快速修复问题的发布模式
    • 如果有多个版本在年龄门槛之外相近时间发布,Bun 会扩展过滤范围,跳过这些可能不稳定的版本,并选择更早发布、更成熟的版本
    • 该检查最多会搜索年龄门槛之后的 7 天;如果在此之后发布仍然很频繁,Bun 会忽略稳定性检查
    • 精确版本请求(如 [email protected])仍会遵守年龄门槛,但会绕过稳定性检查
  • 没有 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

通过环境变量配置

环境变量的优先级高于 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" 是否与预期的软件包名称和版本匹配,来决定是否安装软件包。Bun 使用自定义 JSON 解析器,在找到 "name""version" 后就会停止解析。 当不存在 bun.lock,或者 package.json 中的软件包依赖发生变化时,Bun 会在解析过程中立即下载并提取 tarball。 当存在 bun.lockpackage.json 未发生变化时,Bun 会延迟下载缺失的依赖。如果 node_modules 中预期位置已经存在名称和版本匹配的软件包,Bun 就不会尝试下载 tarball。

CI/CD

在 GitHub Actions 中使用官方 oven-sh/setup-bun 动作安装 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 默认后端,基准测试显示其性能最佳。
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,除非对 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(锁文件版本 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
Bun 会将工作区包列表和 catalog 迁移至 package.json 中的 workspaces 字段:
package.json

目录依赖

支持保留 pnpm 的 catalog: 协议依赖:
package.json

配置迁移

Bun 会从 pnpm-lock.yamlpnpm-workspace.yaml 中迁移以下 pnpm 配置:
  • overridespnpm.overrides 迁移至 package.json 根级 overrides
  • patchedDependenciespnpm.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.yamlpnpm-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
打印此帮助菜单