基本用法
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 install 过滤的详细信息,请参阅 包管理器 > 过滤。
覆盖与解析
Bun 支持package.json 中 npm 的 "overrides" 和 Yarn 的 "resolutions"。它们允许针对依赖的依赖(半依赖)指定版本范围。完整文档参见 包管理器 > 覆盖和解析。
package.json
全局安装包
使用-g 或 --global 参数进行全局安装。通常用于安装命令行工具。
terminal
生产模式
以生产模式安装(不含devDependencies 与 optionalDependencies):
terminal
--frozen-lockfile。此时将安装 bun.lock 指定的确切版本。如果你的 package.json 与 bun.lock 不一致,Bun 会报错退出,且不会更新锁文件。
terminal
bun.lock 锁文件内容,见 包管理器 > 锁文件。
省略依赖
用--omit 标记省略 dev、peer 或 optional 依赖。
terminal
演练模式
执行演练(不实际安装任何东西):terminal
非 npm 依赖
Bun 支持从 Git、GitHub 和本地或远程 tar 包安装依赖。完整文档见 包管理器 > Git、GitHub 和 tarball 依赖。package.json
安装策略
Bun 支持两种包安装策略,决定依赖如何组织在node_modules 中:
扁平安装(Hoisted installs)
传统 npm/Yarn 方式,将依赖扁平化合并到共享的node_modules 目录:
terminal
隔离安装(Isolated installs)
类似 pnpm 的方式,创建严格的依赖隔离,防止幻影依赖:terminal
node_modules/.bun/ 创建中央包存储,并在顶层 node_modules 中使用符号链接,确保包只能访问声明的依赖。
默认策略
默认链接器策略依据是否是新项目或已有项目:- 新工作区/monorepo:
isolated(防止幻影依赖) - 新单包项目:
hoisted(传统 npm 行为) - 旧项目(v1.3.2 之前创建):
hoisted(保留向后兼容)
configVersion 字段控制。详情见 包管理器 > 隔离安装。
最小发布年龄
为防止供应链攻击(恶意包快速发布),可以配置 npm 包的最小发布时间。发布早于此阈值(秒)的版本才会被允许安装。terminal
bunfig.toml 配置:
bunfig.toml
- 只影响新包版本解析 - 已有
bun.lock中的包不变 - 解析时所有依赖(直接及传递)均经过年龄过滤
- 被过滤的版本触发稳定性检测,防止快速发布的无效版本被安装
- 若发现多版本间隔接近年龄门限,会延长过滤期,选择更稳定更旧版本
- 搜索时间最长为 7 天,若仍快速发布则跳过稳定性检测
- 精确版本请求(如
[email protected])仍受年龄限制但绕过稳定性检测
- 无
time字段视为通过年龄检测(npm registry 通常总有时间戳)
配置
通过 bunfig.toml 配置 bun install
bunfig.toml 会在 bun install、bun remove 和 bun add 时搜索:
$XDG_CONFIG_HOME/.bunfig.toml或$HOME/.bunfig.toml- 当前目录下的
./bunfig.toml
bunfig.toml 配置为可选。Bun 力图零配置但非所有功能无配置可用。bun install 默认行为可在此配置,以下为默认值。
bunfig.toml
通过环境变量配置
环境变量优先级高于bunfig.toml。
| 名称 | 描述 |
|---|---|
BUN_CONFIG_REGISTRY | 设置 npm 仓库(默认:https://registry.npmjs.org) |
BUN_CONFIG_TOKEN | 设置授权令牌(当前无实际功能) |
BUN_CONFIG_YARN_LOCKFILE | 保存 Yarn v1 风格的 yarn.lock |
BUN_CONFIG_LINK_NATIVE_BINS | 指向 platform-specific 的 bin 依赖 |
BUN_CONFIG_SKIP_SAVE_LOCKFILE | 不保存锁文件 |
BUN_CONFIG_SKIP_LOAD_LOCKFILE | 不读取锁文件 |
BUN_CONFIG_SKIP_INSTALL_PACKAGES | 不安装任何包 |
clonefile,在 Linux 默认使用 hardlink 安装方法,这样性能最佳。可用 --backend 参数切换安装后端。不可用或错误时,clonefile 和 hardlink 会降级使用平台特定复制实现。
Bun 将从 npm 下载的包缓存至 ~/.bun/install/cache/${name}@${version}。若 semver 版本包含 build 或 pre 标签,则用该值哈希替代。此举可减少路径过长导致的错误,但可能使查找包安装路径更复杂。
当 node_modules 存在时,Bun 会检查 node_modules/package/package.json 中的 "name" 和 "version" 是否符合预期来决定是否安装。它使用自定义 JSON 解析,一旦读取这两个字段即停止。
若无 bun.lock 或 package.json 依赖变更,Bun 会在解析时主动下载并解压 tar 包。
存在 bun.lock 且 package.json 未变时,Bun 懒加载缺失依赖。若期望位置已有匹配的包,Bun 将不下载 tar 包。
CI/CD
在 GitHub Actions 中使用官方oven-sh/setup-bun 动作安装 Bun:
.github/workflows/release.yml
bun ci 确保 package.json 与锁文件同步,不符时构建失败:
terminal
bun install --frozen-lockfile,从锁文件安装精确版本,且 package.json 不匹配时失败。使用 bun ci 或 bun install --frozen-lockfile 必须版本控制中提交 bun.lock。
使用时将 bun install 替换为 bun ci。
.github/workflows/release.yml
平台特定依赖?
Bun 在锁文件中存储来自 npm 的 normalizedcpu 和 os 值及解析的包。针对当前运行时禁用的包,跳过下载、解压和安装。这意味着不同平台/架构安装的包会不同,但锁文件保持一致。
--cpu 和 --os 参数
你可以覆盖目标平台进行包选择:
--cpu 值:arm64、x64、ia32、ppc64、s390x
可用 --os 值:linux、darwin、win32、freebsd、openbsd、sunos、aix
Peer 依赖?
Peer 依赖处理与 yarn 类似。bun install 会自动安装 peer 依赖。如 peerDependenciesMeta 中标记为可选,且已有依赖可用,会优先使用已有依赖。
锁文件
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。使用哈希避免为 scoped 包创建多层目录。
Bun 使用 Cache-Control 忽略 Age 以提升性能,可能导致缓存数据比 npm 注册表晚约 5 分钟。
pnpm 迁移
当检测到pnpm-lock.yaml 且无 bun.lock 时,Bun 会自动在安装时将 pnpm 锁文件迁移为 bun.lock。迁移不会修改原始 pnpm-lock.yaml。
terminal
bun.lock 时执行,当前无禁止迁移的选项。
迁移内容:
锁文件迁移
- 将
pnpm-lock.yaml转换成bun.lock格式 - 保留版本和解析信息
- 保持依赖关系及 peer 依赖
- 支持补丁依赖并含数据完整性哈希
工作区配置
检测到pnpm-workspace.yaml 时,将工作区配置迁移至根 package.json:
pnpm-workspace.yaml
workspaces 字段:
package.json
目录依赖
支持 pnpm 的catalog: 协议依赖保留:
package.json
配置迁移
将 pnpm 配置从pnpm-lock.yaml 和 pnpm-workspace.yaml 迁移至根部:
- 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 依赖必须在目录定义中存在
pnpm-lock.yaml 和 pnpm-workspace.yaml。
CLI 用法
terminal
通用配置
指定配置文件路径(bunfig.toml)
设置特定的当前工作目录
依赖范围与管理
不安装 devDependencies
不更新 package.json 也不保存锁文件
保存到 package.json
从安装中排除 ‘dev’、‘optional’ 或 ‘peer’ 依赖
仅当依赖不存在于 package.json 中时才添加
依赖类型与版本控制
添加依赖到 “devDependencies”
添加依赖到 “optionalDependencies”
添加依赖到 “peerDependencies”
添加确切版本,而非 ^ 范围版本
锁文件控制
写入 yarn.lock 文件(yarn v1)
不允许修改锁文件
保存基于文本的锁文件
仅生成锁文件,不安装依赖
网络与注册表设置
提供证书颁发机构(CA)签名证书
证书颁发机构签名证书的文件路径
默认使用指定注册表,覆盖 .npmrc、bunfig.toml 和环境变量
安装过程控制
不执行任何安装操作
总是从注册表请求最新版本并重新安装所有依赖
全局安装
平台特定优化选项:“clonefile”、“hardlink”、“symlink”、“copyfile”
为匹配的工作区安装包
递归分析并安装作为参数传入文件的所有依赖
缓存选项
从特定目录路径存储和加载缓存数据
完全忽略清单缓存
输出与日志记录
不输出任何日志
过度详细的日志输出
禁用进度条
不打印摘要
安全与完整性
跳过新下载包的完整性验证
添加至项目 package.json 的 trustedDependencies 并安装包
并发与性能
生命周期脚本的最大并发任务数
最大并发网络请求数
生命周期脚本管理
跳过项目 package.json 中的生命周期脚本(依赖的脚本不会被执行)
帮助信息
打印此帮助菜单