Skip to main content

基本用法

terminal
bun install react
bun install [email protected] # 指定版本
bun install react@latest # 指定标签
bun CLI 包含一个兼容 Node.js 的包管理器,旨在极大地加速替代 npmyarnpnpm。它是一个独立工具,可以在已有的 Node.js 项目中工作;如果你的项目中有 package.jsonbun 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
# 如果返回版本号 >= 5.6,则无需操作
uname -r

# 安装 Ubuntu 官方硬件支持内核
sudo apt install --install-recommends linux-generic-hwe-20.04
安装项目中所有依赖:
terminal
bun install
执行 bun install 时会:
  • 安装 所有 dependenciesdevDependenciesoptionalDependencies。Bun 默认也会安装 peerDependencies
  • 运行 项目的 {pre|post}install{pre|post}prepare 脚本,且在合适的时机执行。出于安全考虑,Bun 不会执行 已安装依赖的生命周期脚本。
  • 写入 一个 bun.lock 锁文件到项目根目录。

日志记录

调整日志详情级别:
terminal
bun install --verbose # 调试日志
bun install --silent  # 静默无日志

生命周期脚本

与其他 npm 客户端不同,Bun 不会执行安装依赖的任意生命周期脚本(如 postinstall)。执行任意脚本存在潜在安全风险。 若需允许 Bun 针对特定包执行生命周期脚本,请在你的 package.json 中将该包添加到 trustedDependencies 字段。
package.json
{
  "name": "my-app",
  "version": "1.0.0",
  "trustedDependencies": ["my-trusted-package"] 
}
随后重新安装该包,Bun 会读取此字段并为 my-trusted-package 运行生命周期脚本。 生命周期脚本安装时并行运行。调整最大并行脚本数量使用 --concurrent-scripts 参数。默认值为报告的 CPU 核心数或 GOMAXPROCS 的两倍。
terminal
bun install --concurrent-scripts 5
Bun 会自动优化知名包(如 esbuildsharp 等)的 postinstall 脚本,确定必需运行的脚本。若想关闭此优化:
terminal
BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

工作区(Workspaces)

Bun 支持 package.json 中的 "workspaces"。完整文档请参考 包管理器 > 工作区
package.json
{
  "name": "my-app",
  "version": "1.0.0",
  "workspaces": ["packages/*"], 
  "dependencies": {
    "preact": "^10.5.13"
  }
}

为特定包安装依赖

在 monorepo 中,可以通过 --filter 参数针对部分包安装依赖。
terminal
# 为除了 `pkg-c` 之外的所有工作区安装依赖
bun install --filter '!pkg-c'

# 仅为 `./packages/pkg-a` 中的 `pkg-a` 安装依赖
bun install --filter './packages/pkg-a'
有关 bun install 过滤的详细信息,请参阅 包管理器 > 过滤

覆盖与解析

Bun 支持 package.json 中 npm 的 "overrides" 和 Yarn 的 "resolutions"。它们允许针对依赖的依赖(半依赖)指定版本范围。完整文档参见 包管理器 > 覆盖和解析
package.json
{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "overrides": { 
    "bar": "~4.4.0"
  } 
}

全局安装包

使用 -g--global 参数进行全局安装。通常用于安装命令行工具。
terminal
bun install --global cowsay # 或 `bun install -g cowsay`
cowsay "Bun!"
 ______
< Bun! >
 ------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

生产模式

以生产模式安装(不含 devDependenciesoptionalDependencies):
terminal
bun install --production
为实现可复现安装,请使用 --frozen-lockfile。此时将安装 bun.lock 指定的确切版本。如果你的 package.jsonbun.lock 不一致,Bun 会报错退出,且不会更新锁文件。
terminal
bun install --frozen-lockfile
更多关于 bun.lock 锁文件内容,见 包管理器 > 锁文件

省略依赖

--omit 标记省略 dev、peer 或 optional 依赖。
terminal
# 从安装中排除 "devDependencies"。同时适用于根包和工作区(若存在)。传递依赖不会拥有 devDependencies。
bun install --omit dev

# 仅安装 "dependencies"
bun install --omit=dev --omit=peer --omit=optional

演练模式

执行演练(不实际安装任何东西):
terminal
bun install --dry-run

非 npm 依赖

Bun 支持从 Git、GitHub 和本地或远程 tar 包安装依赖。完整文档见 包管理器 > Git、GitHub 和 tarball 依赖
package.json
{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "moment": "[email protected]:moment/moment.git",
    "zod": "github:colinhacks/zod",
    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
    "bun-types": "npm:@types/bun"
  }
}

安装策略

Bun 支持两种包安装策略,决定依赖如何组织在 node_modules 中:

扁平安装(Hoisted installs)

传统 npm/Yarn 方式,将依赖扁平化合并到共享的 node_modules 目录:
terminal
bun install --linker hoisted

隔离安装(Isolated installs)

类似 pnpm 的方式,创建严格的依赖隔离,防止幻影依赖:
terminal
bun install --linker isolated
隔离安装会在 node_modules/.bun/ 创建中央包存储,并在顶层 node_modules 中使用符号链接,确保包只能访问声明的依赖。

默认策略

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

最小发布年龄

为防止供应链攻击(恶意包快速发布),可以配置 npm 包的最小发布时间。发布早于此阈值(秒)的版本才会被允许安装。
terminal
# 只安装至少三天前发布的版本
bun add @types/bun --minimum-release-age 259200 # 秒
也可以在 bunfig.toml 配置:
bunfig.toml
[install]
# 最低发布时间为三天
minimumReleaseAge = 259200 # 秒

# 排除信任包绕过年龄检测
minimumReleaseAgeExcludes = ["@types/node", "typescript"]
启用最小年龄过滤时:
  • 只影响新包版本解析 - 已有 bun.lock 中的包不变
  • 解析时所有依赖(直接及传递)均经过年龄过滤
  • 被过滤的版本触发稳定性检测,防止快速发布的无效版本被安装
    • 若发现多版本间隔接近年龄门限,会延长过滤期,选择更稳定更旧版本
    • 搜索时间最长为 7 天,若仍快速发布则跳过稳定性检测
    • 精确版本请求(如 [email protected])仍受年龄限制但绕过稳定性检测
  • time 字段视为通过年龄检测(npm registry 通常总有时间戳)
更高级的安全扫描、集成服务与自定义过滤,见 包管理器 > 安全扫描器 API

配置

通过 bunfig.toml 配置 bun install

bunfig.toml 会在 bun installbun removebun add 时搜索:
  1. $XDG_CONFIG_HOME/.bunfig.toml$HOME/.bunfig.toml
  2. 当前目录下的 ./bunfig.toml
二者均存在时结果合并。 使用 bunfig.toml 配置为可选。Bun 力图零配置但非所有功能无配置可用。bun install 默认行为可在此配置,以下为默认值。
bunfig.toml
[install]

# 是否安装 optionalDependencies
optional = true

# 是否安装 devDependencies
dev = true

# 是否安装 peerDependencies
peer = true

# 等同于 `--production`
production = false

# 等同于 `--save-text-lockfile`
saveTextLockfile = false

# 等同于 `--frozen-lockfile`
frozenLockfile = false

# 等同于 `--dry-run`
dryRun = false

# 等同于 `--concurrent-scripts`
concurrentScripts = 16 # (cpu 核心数或 GOMAXPROCS) x2

# 安装策略:"hoisted" 或 "isolated"
# 默认依赖于锁文件 configVersion 和是否使用工作区:
# - configVersion = 1: 若使用工作区则 "isolated",否则 "hoisted"
# - configVersion = 0: "hoisted"
linker = "hoisted"

# 最小发布时间配置
minimumReleaseAge = 259200 # 秒
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

通过环境变量配置

环境变量优先级高于 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不安装任何包
Bun 在 macOS 默认使用 clonefile,在 Linux 默认使用 hardlink 安装方法,这样性能最佳。可用 --backend 参数切换安装后端。不可用或错误时,clonefilehardlink 会降级使用平台特定复制实现。 Bun 将从 npm 下载的包缓存至 ~/.bun/install/cache/${name}@${version}。若 semver 版本包含 buildpre 标签,则用该值哈希替代。此举可减少路径过长导致的错误,但可能使查找包安装路径更复杂。 node_modules 存在时,Bun 会检查 node_modules/package/package.json 中的 "name""version" 是否符合预期来决定是否安装。它使用自定义 JSON 解析,一旦读取这两个字段即停止。 若无 bun.lockpackage.json 依赖变更,Bun 会在解析时主动下载并解压 tar 包。 存在 bun.lockpackage.json 未变时,Bun 懒加载缺失依赖。若期望位置已有匹配的包,Bun 将不下载 tar 包。

CI/CD

在 GitHub Actions 中使用官方 oven-sh/setup-bun 动作安装 Bun:
.github/workflows/release.yml
name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun install
      - name: Build app
        run: bun run build
对要求可复现构建的 CI/CD 环境,可用 bun ci 确保 package.json 与锁文件同步,不符时构建失败:
terminal
bun ci
等价于 bun install --frozen-lockfile,从锁文件安装精确版本,且 package.json 不匹配时失败。使用 bun cibun install --frozen-lockfile 必须版本控制中提交 bun.lock 使用时将 bun install 替换为 bun ci
.github/workflows/release.yml
name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun ci
      - name: Build app
        run: bun run build

平台特定依赖?

Bun 在锁文件中存储来自 npm 的 normalized cpuos 值及解析的包。针对当前运行时禁用的包,跳过下载、解压和安装。这意味着不同平台/架构安装的包会不同,但锁文件保持一致。

--cpu--os 参数

你可以覆盖目标平台进行包选择:
bun install --cpu=x64 --os=linux
安装指定平台的包,方便跨平台构建或准备不同环境部署。 可用 --cpuarm64x64ia32ppc64s390x 可用 --oslinuxdarwinwin32freebsdopenbsdsunosaix

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 pm cache rm
# 或
rm -rf ~/.bun/install/cache

平台特定后端

bun install 根据平台调用不同系统调用安装依赖以优化性能。可用 --backend 强制指定。 hardlink 是 Linux 默认后端,基准测试显示其性能最佳。
rm -rf node_modules
bun install --backend hardlink
clonefile 是 macOS 默认后端,性能最好,仅 macOS 可用。
rm -rf node_modules
bun install --backend clonefile
clonefile_each_dir 类似 clonefile,但每个目录逐文件克隆。仅 macOS 可用,通常性能不及 clonefile。不支持一次系统调用递归克隆子目录。
rm -rf node_modules
bun install --backend clonefile_each_dir
copyfile 是所有后端失败时的回退方法,速度最慢。macOS 使用 fcopyfile(),Linux 使用 copy_file_range()
rm -rf node_modules
bun install --backend copyfile
symlink 通常仅用于内部 file: 依赖(以及未来的 link:)。为防止循环链接,不会对 node_modules 文件夹做符号链接。 若用 --backend=symlink 安装,除非每个依赖都有自己的 node_modules,否则 Node.js 不会正确解析依赖的 node_modules,除非对 nodebun 使用 --preserve-symlinks 参数。详见 Node.js 关于 --preserve-symlinks 文档
rm -rf node_modules
bun install --backend symlink
bun --preserve-symlinks ./my-file.js
node --preserve-symlinks ./my-file.js # https://nodejs.org/api/cli.html#--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 install
注意:迁移仅在无 bun.lock 时执行,当前无禁止迁移的选项。 迁移内容:

锁文件迁移

  • pnpm-lock.yaml 转换成 bun.lock 格式
  • 保留版本和解析信息
  • 保持依赖关系及 peer 依赖
  • 支持补丁依赖并含数据完整性哈希

工作区配置

检测到 pnpm-workspace.yaml 时,将工作区配置迁移至根 package.json
pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

catalogs:
  build:
    webpack: ^5.0.0
    babel: ^7.0.0
工作区包列表和目录将移至 workspaces 字段:
package.json
{
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^18.0.0",
      "typescript": "^5.0.0"
    },
    "catalogs": {
      "build": {
        "webpack": "^5.0.0",
        "babel": "^7.0.0"
      }
    }
  }
}

目录依赖

支持 pnpm 的 catalog: 协议依赖保留:
package.json
{
  "dependencies": {
    "react": "catalog:",
    "webpack": "catalog:build"
  }
}

配置迁移

将 pnpm 配置从 pnpm-lock.yamlpnpm-workspace.yaml 迁移至根部:
  • overridespnpm.overrides 迁移至 package.json 根级 overrides
  • patchedDependenciespnpm.patchedDependencies 迁移至 package.json 根级 patchedDependencies
  • workspace overrides 应用自 pnpm-workspace.yaml 至根 package.json

要求

  • 需 pnpm 锁文件版本至少 7
  • 工作区包需提供 package.jsonname 字段
  • 目录下所有 catalog 依赖必须在目录定义中存在
迁移完成后,可以安全删除 pnpm-lock.yamlpnpm-workspace.yaml

CLI 用法

terminal
bun install <name>@<version>

通用配置

--config
string
指定配置文件路径(bunfig.toml)
--cwd
string
设置特定的当前工作目录

依赖范围与管理

--production
boolean
不安装 devDependencies
--no-save
boolean
不更新 package.json 也不保存锁文件
--save
boolean
default:"true"
保存到 package.json
--omit
string
从安装中排除 ‘dev’、‘optional’ 或 ‘peer’ 依赖
--only-missing
boolean
仅当依赖不存在于 package.json 中时才添加

依赖类型与版本控制

--dev
boolean
添加依赖到 “devDependencies”
--optional
boolean
添加依赖到 “optionalDependencies”
--peer
boolean
添加依赖到 “peerDependencies”
--exact
boolean
添加确切版本,而非 ^ 范围版本

锁文件控制

--yarn
boolean
写入 yarn.lock 文件(yarn v1)
--frozen-lockfile
boolean
不允许修改锁文件
--save-text-lockfile
boolean
保存基于文本的锁文件
--lockfile-only
boolean
仅生成锁文件,不安装依赖

网络与注册表设置

--ca
string
提供证书颁发机构(CA)签名证书
--cafile
string
证书颁发机构签名证书的文件路径
--registry
string
默认使用指定注册表,覆盖 .npmrc、bunfig.toml 和环境变量

安装过程控制

--dry-run
boolean
不执行任何安装操作
--force
boolean
总是从注册表请求最新版本并重新安装所有依赖
--global
boolean
全局安装
--backend
string
default:"clonefile"
平台特定优化选项:“clonefile”、“hardlink”、“symlink”、“copyfile”
--filter
string
为匹配的工作区安装包
--analyze
boolean
递归分析并安装作为参数传入文件的所有依赖

缓存选项

--cache-dir
string
从特定目录路径存储和加载缓存数据
--no-cache
boolean
完全忽略清单缓存

输出与日志记录

--silent
boolean
不输出任何日志
--verbose
boolean
过度详细的日志输出
--no-progress
boolean
禁用进度条
--no-summary
boolean
不打印摘要

安全与完整性

--no-verify
boolean
跳过新下载包的完整性验证
--trust
boolean
添加至项目 package.json 的 trustedDependencies 并安装包

并发与性能

--concurrent-scripts
number
default:"5"
生命周期脚本的最大并发任务数
--network-concurrency
number
default:"48"
最大并发网络请求数

生命周期脚本管理

--ignore-scripts
boolean
跳过项目 package.json 中的生命周期脚本(依赖的脚本不会被执行)

帮助信息

--help
boolean
打印此帮助菜单