Bun 安装与配置 #

系统要求 #

支持的平台 #

平台 架构 最低版本
macOS x64, ARM64 (M1/M2) macOS 10.15+
Linux x64, ARM64 glibc 2.17+
Windows x64 Windows 10+

硬件要求 #

text 
最低配置:
├── CPU: 1 核
├── 内存: 512 MB
└── 磁盘: 100 MB

推荐配置:
├── CPU: 2+ 核
├── 内存: 1+ GB
└── 磁盘: 200 MB

安装方式 #

方式一：curl 安装（推荐） #

macOS / Linux #

bash 
# 使用 curl 安装
curl -fsSL https://bun.sh/install | bash

# 使用 wget 安装
wget -qO- https://bun.sh/install | bash

安装完成后，重启终端或执行：

bash 
source ~/.bashrc
# 或
source ~/.zshrc

方式二：npm 安装 #

bash 
# 使用 npm 全局安装
npm install -g bun

# 使用 yarn 安装
yarn global add bun

方式三：Homebrew 安装（macOS） #

bash 
# 添加 tap
brew tap oven-sh/bun

# 安装 Bun
brew install oven-sh/bun/bun

方式四：Scoop 安装（Windows） #

powershell 
# 使用 Scoop 安装
scoop install bun

方式五：PowerShell 安装（Windows） #

powershell 
powershell -c "irm bun.sh/install.ps1 | iex"

方式六：Docker 安装 #

bash 
# 拉取官方镜像
docker pull oven/bun

# 运行容器
docker run --rm -it oven/bun bun --version

# 挂载项目目录运行
docker run --rm -it -v $(pwd):/app -w /app oven/bun bun run index.ts

验证安装 #

检查版本 #

bash 
# 查看 Bun 版本
bun --version

# 输出示例
# 1.2.0

检查安装路径 #

bash 
# 查看 Bun 安装位置
which bun

# 输出示例
# /Users/username/.bun/bin/bun

运行测试 #

bash 
# 快速测试
bun -e "console.log('Hello, Bun!')"

# 输出
# Hello, Bun!

版本管理 #

升级 Bun #

bash 
# 升级到最新版本
bun upgrade

# 升级到指定版本
bun upgrade bun@1.2.0

# 升级到 canary 版本
bun upgrade --canary

使用版本管理工具 #

使用 bunx #

bash 
# 运行特定版本的 Bun
bunx bun@1.1.0 run script.ts

使用 Volta #

bash 
# 安装 Volta
curl https://get.volta.sh | bash

# 使用 Volta 安装 Bun
volta install bun

# 设置项目特定版本
volta pin bun@1.2.0

使用 nvm 风格管理 #

bash 
# Bun 目前没有官方的 nvm 等效工具
# 可以手动管理多个版本

# 安装特定版本到自定义目录
curl -fsSL https://github.com/oven-sh/bun/releases/download/bun-v1.1.0/bun-darwin-x64.zip -o bun-1.1.0.zip
unzip bun-1.1.0.zip -d ~/.bun-versions/1.1.0

# 创建符号链接切换版本
ln -sfn ~/.bun-versions/1.1.0/bun ~/.bun/bin/bun

环境配置 #

环境变量 #

Bun 会自动读取以下环境变量：

bash 
# Bun 安装目录
BUN_INSTALL=/Users/username/.bun

# 添加到 PATH
export PATH="$BUN_INSTALL/bin:$PATH"

# 自定义缓存目录
BUN_CACHE_DIR=/path/to/cache

# 自定义安装目录
BUN_INSTALL=/custom/path

配置文件位置 #

text 
~/.bun/
├── bin/           # Bun 可执行文件
│   └── bun
├── install/       # 安装缓存
├── cache/         # 包缓存
└── .bunfig        # 全局配置文件

全局配置文件 #

创建 ~/.bunfig 文件：

toml 
# ~/.bunfig

# 默认注册表
[install]
registry = "https://registry.npmjs.org"

# 中国镜像
# registry = "https://registry.npmmirror.com"

# 全局安装目录
globalDir = "~/.bun/global"

# 缓存设置
[install.cache]
dir = "~/.bun/cache"
disable = false

Shell 补全 #

Bash #

bash 
# 添加到 ~/.bashrc
source <(bun completions bash)

# 或手动添加
echo 'source <(bun completions bash)' >> ~/.bashrc
source ~/.bashrc

Zsh #

bash 
# 添加到 ~/.zshrc
source <(bun completions zsh)

# 或手动添加
echo 'source <(bun completions zsh)' >> ~/.zshrc
source ~/.zshrc

Fish #

bash 
# 添加到 Fish 配置
bun completions fish > ~/.config/fish/completions/bun.fish

PowerShell #

powershell 
# 添加到 PowerShell 配置
bun completions powershell >> $PROFILE

项目配置 #

bunfig.toml #

在项目根目录创建 bunfig.toml：

toml 
# bunfig.toml

# 运行时配置
[run]
# 预加载文件
preload = ["./setup.ts"]

# 安装配置
[install]
# 精确版本
exact = true
# 生产依赖
production = false
# 离线模式
offline = false

# 锁文件行为
[install.lockfile]
# 保存锁文件
save = true
# 打印 yarn 格式
print = "yarn"

# 测试配置
[test]
# 覆盖率
coverage = true
# 并行运行
jobs = 4

TypeScript 配置 #

Bun 会自动读取 tsconfig.json：

json 
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "types": ["bun-types"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

安装类型定义 #

bash 
# 安装 Bun 类型定义
bun add -d bun-types

IDE 集成 #

VS Code #

安装插件 #

  1. Bun for VS Code - 官方插件
  2. TypeScript - 内置支持

配置 settings.json #

json 
{
  "bun.runtime": "/Users/username/.bun/bin/bun",
  "bun.packageManager": "bun",
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}
#### 配置 launch.json

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Bun: Run",
      "runtimeExecutable": "/Users/username/.bun/bin/bun",
      "runtimeArgs": ["run", "${file}"],
      "cwd": "${workspaceFolder}"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Bun: Test",
      "runtimeExecutable": "/Users/username/.bun/bin/bun",
      "runtimeArgs": ["test"],
      "cwd": "${workspaceFolder}"
    }
  ]
}

WebStorm #

  1. 打开 Preferences → Languages & Frameworks → TypeScript
  2. 设置 Package manager 为 bun
  3. 配置 Node interpreter 为 Bun 路径

常见问题 #

安装失败 #

权限问题 #

bash 
# macOS/Linux 权限问题
sudo chown -R $(whoami) ~/.bun

# 或重新安装
curl -fsSL https://bun.sh/install | bash

网络问题 #

bash 
# 使用代理
export https_proxy=http://127.0.0.1:7890
curl -fsSL https://bun.sh/install | bash

# 或使用镜像
curl -fsSL https://ghproxy.com/https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-x64.zip -o bun.zip

Windows 特有问题 #

PowerShell 执行策略 #

powershell 
# 允许脚本执行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

路径问题 #

powershell 
# 手动添加到 PATH
$env:Path += ";C:\Users\Username\.bun\bin"

版本冲突 #

bash 
# 检查是否有多个 Bun 安装
which -a bun

# 删除旧版本
rm -rf ~/.bun

# 重新安装
curl -fsSL https://bun.sh/install | bash

Node.js 兼容问题 #

bash 
# 如果项目依赖 Node.js 特定版本
# 可以同时使用 Volta 管理

# 安装 Volta
curl https://get.volta.sh | bash

# 设置 Node.js 版本
volta install node@18

# 设置 Bun 版本
volta install bun

卸载 Bun #

完全卸载 #

bash 
# 删除 Bun 目录
rm -rf ~/.bun

# 从 shell 配置中移除
# 编辑 ~/.bashrc 或 ~/.zshrc
# 删除以下行:
# export BUN_INSTALL="$HOME/.bun"
# export PATH="$BUN_INSTALL/bin:$PATH"

# Homebrew 安装的
brew uninstall bun

清理缓存 #

bash 
# 清理包缓存
rm -rf ~/.bun/cache
rm -rf ~/.bun/install

# 清理全局安装的包
rm -rf ~/.bun/global

下一步 #

安装完成后，继续学习 Hello World 编写你的第一个 Bun 程序！

最后更新：2026-03-29