5分钟极速部署：Bun全平台安装与管理指南

1. 环境准备：系统要求与依赖检查

Bun是一个集JavaScript运行时环境（类似Node.js的程序执行平台）、包管理器、测试运行器和打包工具于一体的现代化开发工具。在开始安装前，请确保您的系统满足以下要求：

系统兼容性矩阵

• Linux：内核5.6+（最低5.1），需安装unzip工具（可通过sudo apt install unzip获取）
• macOS：10.15+（Catalina或更高版本）
• Windows：Windows 10 1809+或Windows 11，需启用WSL2或直接运行原生版本

💡 技巧：Linux用户可通过uname -r命令检查内核版本，建议使用Ubuntu 20.04+、Fedora 34+或Debian 11+以获得最佳体验。

硬件建议

• 最低配置：2核CPU，4GB内存，100MB可用磁盘空间
• 推荐配置：4核CPU，8GB内存，SSD存储（可显著提升依赖安装速度）

2. 多渠道部署：选择最适合你的安装方式

安装方式对比与选择

安装方式	适用场景	优势	劣势	操作难度
curl一键安装	Linux/macOS快速部署	无需预先安装包管理器	需手动配置PATH	⭐⭐☆☆☆
npm安装	已有Node.js环境	集成现有Node生态	依赖Node运行时	⭐☆☆☆☆
Homebrew	macOS用户	自动处理依赖	仅限macOS	⭐☆☆☆☆
Scoop	Windows用户	沙箱化管理	需先安装Scoop	⭐⭐☆☆☆
Docker	隔离环境需求	环境一致性	性能开销	⭐⭐☆☆☆

分平台安装指南

🔍 Linux/macOS核心安装方案

curl一键部署（推荐）：

curl -fsSL https://bun.sh/install | bash

Homebrew用户专属：

brew install oven-sh/bun/bun

npm兼容安装：

npm install -g bun

验证要点：安装完成后关闭并重新打开终端，确保环境变量生效。

🔍 Windows平台安装选项

PowerShell快速部署：

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

Scoop包管理：

scoop install bun

⚠️ 警告：Windows用户若使用WSL2安装，需确保WSL2内核版本≥5.10.60.1，可通过wsl --update命令升级。

🔍 容器化部署方案

Docker用户可直接使用官方镜像：

docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun bun --version

💡 技巧：添加-v $(pwd):/app -w /app参数可将当前目录挂载到容器中，方便开发使用。

图1：Bun与主流打包工具的性能对比，展示了Bun在构建速度上的显著优势

3. 验证与调试：确保安装正确

基础验证步骤

1. 版本检查：

bun --version

预期输出：类似1.x.y的版本号字符串

2. 功能测试：

bun run https://bun.sh/examples/hello.ts

预期输出：Hello from Bun!

3. 环境变量验证：

echo $BUN_INSTALL  # Linux/macOS
echo %BUN_INSTALL%  # Windows

预期输出：Bun的安装路径（通常为~/.bun或%USERPROFILE%\.bun）

常见问题诊断

问题1："bun: command not found"

解决步骤：

1. 检查安装日志是否有错误信息
2. 手动添加环境变量：

# Linux/macOS
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
source ~/.bashrc  # 或对应shell的配置文件

# Windows PowerShell
[System.Environment]::SetEnvironmentVariable(
    "Path",
    [System.Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.bun\bin",
    [System.EnvironmentVariableTarget]::User
)

问题2：Linux系统GLIBC版本错误

解决步骤：

1. 检查系统GLIBC版本：ldd --version
2. 若版本低于2.28，安装musl版本：

curl -fsSL https://bun.sh/install | bash -s -- --platform linux-x64-musl

问题3：Windows安装后无法启动

解决步骤：

1. 确保已安装Visual C++运行时
2. 尝试PowerShell命令修复：

sfc /scannow
DISM /Online /Cleanup-Image /RestoreHealth

4. 版本控制：灵活管理Bun版本

版本选择决策树

是否需要最新功能？
├─ 是 → Canary版本 (bun upgrade --canary)
└─ 否 → 是否需要特定版本？
   ├─ 是 → 指定版本安装 (curl ... "bun-v1.x.y")
   └─ 否 → 稳定版 (bun upgrade --stable)

核心版本操作命令

升级到最新稳定版：

bun upgrade

安装特定版本：

# Linux/macOS
curl -fsSL https://bun.sh/install | bash -s "bun-v1.0.0"

# Windows
iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.0.0"

切换Canary版本：

bun upgrade --canary  # 切换到每日构建版
bun upgrade --stable   # 切回稳定版

验证要点：版本切换后执行bun --version确认版本号已更新。

⚠️ 警告：生产环境建议使用稳定版，Canary版本可能包含未测试的新功能。

5. 高级操作：定制与卸载

自定义安装路径

Linux/macOS用户可通过环境变量指定安装路径：

BUN_INSTALL=/opt/bun curl -fsSL https://bun.sh/install | bash

源码构建（开发者选项）

如需从源码构建最新版本：

git clone https://gitcode.com/GitHub_Trending/bu/bun
cd bun
make install

彻底卸载Bun

根据安装方式选择对应的卸载方法：

curl安装方式：

rm -rf ~/.bun

Windows PowerShell卸载：

powershell -c ~\.bun\uninstall.ps1

包管理器安装：

# Homebrew
brew uninstall bun

# Scoop
scoop uninstall bun

# npm
npm uninstall -g bun

验证要点：卸载后执行bun --version应提示"command not found"。

进阶学习路径

1. 基础使用：

   • 快速入门：docs/quickstart.mdx
   • 命令参考：docs/cli.mdx

2. 核心功能：

   • 打包工具：docs/bundler/index.mdx
   • 测试运行器：docs/test/index.mdx
   • 包管理器：docs/pm/index.mdx

3. 高级主题：

   • 插件开发：docs/bundler/plugins.mdx
   • 性能优化：docs/guides/performance.mdx
   • 部署策略：docs/guides/deployment/index.mdx

通过以上指南，您已掌握Bun的全平台安装与管理方法。Bun作为新一代JavaScript工具链，将为您的开发工作流带来显著的效率提升。