Bun运行时环境安装与配置完全指南

Bun是一个集JavaScript运行时环境、包管理器、测试运行器和打包工具于一体的现代化开发工具。本指南将帮助开发初学者从零开始安装、配置并高效使用Bun，通过清晰的步骤和场景化描述，让你快速掌握这个高性能工具的核心使用方法。

环境准备

在开始安装Bun之前，需要确保你的系统满足基本要求并做好必要准备。这些准备工作将确保安装过程顺利进行，并避免常见的兼容性问题。

系统要求检查

Bun作为一款现代运行时，对系统环境有特定要求：

• Linux系统：需要内核版本5.6或更高（最低支持5.1版本）

  💡 为什么需要较新的内核版本？Bun使用了Linux内核的io_uring特性来实现高效I/O操作，这一特性在5.1版本中引入，5.6版本中得到显著改进，能提供更好的性能和稳定性。

• Windows系统：需要Windows 10版本1809或更高

  💡 Windows用户注意：版本1809引入了WSL 2和必要的系统API支持，确保Bun能正常运行各种系统调用。

• macOS系统：需要macOS 10.15 (Catalina)或更高版本

必要依赖安装

Linux系统准备

大多数Linux发行版需要安装unzip工具来处理Bun的安装包：

sudo apt update  # 更新软件包索引
sudo apt install unzip -y  # 安装解压缩工具

📌 关键提示：如果你使用的是Fedora、CentOS等RPM系发行版，请使用yum install unzip或dnf install unzip命令

Windows系统准备

Windows用户需要确保已启用PowerShell执行策略：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser  # 允许运行本地脚本

💡 执行此命令后，系统会提示确认，输入Y并按回车即可。这一步是为了允许运行Bun的安装脚本。

核心安装

Bun提供了多种安装方式，我们将重点介绍官方推荐的方法，并提供多种选择以适应不同开发环境。

主流安装方法

方法一：使用官方安装脚本（推荐）

这是最直接且官方推荐的安装方式，适用于macOS和Linux系统：

curl -fsSL https://bun.sh/install | bash  # 下载并执行Bun安装脚本

📌 关键提示：当你在终端看到"Successfully installed Bun!"提示时，表示核心程序已安装完成，但可能需要配置环境变量才能立即使用。

方法二：通过包管理器安装

对于喜欢使用系统包管理器的用户，Bun提供了多种选择：

Homebrew (macOS/Linux)

brew tap oven-sh/bun  # 添加Bun的Homebrew仓库
brew install bun      # 安装Bun

Scoop (Windows)

scoop bucket add extras       # 添加extras仓库
scoop install bun            # 安装Bun

方法三：npm安装

如果你已经安装了Node.js环境，可以通过npm安装Bun：

npm install -g bun  # 通过npm全局安装Bun

💡 这种方式会下载预编译的Bun二进制文件，不需要从源码编译，适合已有Node.js环境的开发者。

特定版本安装

如需安装特定版本的Bun（如测试版或历史版本），可以使用以下方法：

Linux/macOS系统

# 安装1.0.0版本（请替换为实际需要的版本号）
curl -fsSL https://bun.sh/install | bash -s "bun-v1.0.0"

Windows系统

# 安装1.0.0版本（请替换为实际需要的版本号）
iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.0.0"

配置验证

安装完成后，需要验证Bun是否正确安装并配置，确保可以在终端中正常使用。

基础验证

打开新的终端窗口，执行以下命令检查Bun版本：

bun --version  # 显示Bun版本号，如1.0.0

📌 关键提示：如果终端显示"bun: command not found"，说明Bun的安装目录尚未添加到系统PATH环境变量中。

PATH环境变量配置

Linux/macOS系统配置

根据你使用的shell，将以下内容添加到对应的配置文件中（如~/.bashrc、~/.zshrc等）：

export BUN_INSTALL="$HOME/.bun"       # 设置Bun安装目录
export PATH="$BUN_INSTALL/bin:$PATH"  # 将Bun的可执行目录添加到PATH

保存文件后，执行以下命令使配置立即生效：

source ~/.bashrc  # 或对应的配置文件，如source ~/.zshrc

Windows系统配置

通过PowerShell执行以下命令添加环境变量：

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

📌 关键提示：配置完成后需要关闭并重新打开所有终端窗口，新的环境变量才能生效。

功能验证

为确保Bun的核心功能正常工作，可以创建一个简单的JavaScript文件进行测试：

echo "console.log('Hello Bun!')" > hello.js  # 创建测试文件
bun run hello.js  # 运行测试文件

如果终端输出"Hello Bun!"，则表示Bun已正确安装并可以正常运行JavaScript代码。

版本管理

Bun提供了灵活的版本管理功能，让你可以轻松升级、降级或切换不同版本的Bun。

版本升级方法对比

安装方式	升级命令	说明
官方脚本	bun upgrade	自我升级到最新稳定版
Homebrew	brew upgrade bun	通过Homebrew更新
Scoop	scoop update bun	通过Scoop包管理器更新
npm	npm update -g bun	通过npm更新全局安装的Bun

安装Canary版本

Canary版本包含最新开发特性，适合想要体验前沿功能的开发者：

bun upgrade --canary  # 升级到最新Canary版本

📌 关键提示：Canary版本可能不稳定，不建议用于生产环境。测试完成后，可使用bun upgrade --stable命令回到稳定版。

多版本管理

如果需要在多个Bun版本间切换，可以使用版本管理工具如asdf：

# 安装asdf插件
asdf plugin add bun https://gitcode.com/GitHub_Trending/bu/bun.git

# 安装特定版本
asdf install bun 1.0.0

# 设置全局版本
asdf global bun 1.0.0

# 设置当前目录版本
asdf local bun 1.0.0

高级操作

除了基本安装和使用外，Bun还提供了一些高级功能和操作方式，适合不同场景下的使用需求。

从源码构建

对于需要自定义编译选项或贡献代码的开发者，可以从源码构建Bun：

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/bu/bun.git
cd bun

# 构建Bun
make  # 或根据平台使用对应的构建命令

💡 从源码构建需要安装额外的构建依赖，包括C编译器、CMake、Ninja等工具。详细构建指南可参考项目中的CONTRIBUTING.md文件。

Docker容器化使用

Bun提供官方Docker镜像，适合在容器环境中使用：

# 拉取最新镜像
docker pull oven/bun

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

可以将本地项目挂载到容器中运行：

docker run --rm -v $(pwd):/app -w /app oven/bun bun run index.js

离线安装

对于网络受限环境，可以先下载Bun二进制文件，然后手动安装：

1. 从Bun官方网站下载对应平台的二进制包
2. 解压到指定目录：mkdir -p ~/.bun && tar -xf bun-*.tar.xz -C ~/.bun
3. 手动添加PATH环境变量（参考配置验证部分）

问题解决

在Bun的安装和使用过程中，可能会遇到一些常见问题。以下是几个典型案例及解决方案。

案例一：命令未找到 (command not found)

错误信息：bash: bun: command not found

原因定位：Bun的安装目录未添加到系统PATH环境变量中，或配置后未重启终端。

解决方案：

1. 确认Bun安装路径：ls ~/.bun/bin（应看到bun可执行文件）
2. 检查PATH配置：echo $PATH（确认包含~/.bun/bin）
3. 重新加载配置文件：source ~/.bashrc
4. 如仍未解决，手动执行：export PATH="$HOME/.bun/bin:$PATH"

案例二：GLIBC版本不兼容

错误信息：bun: /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.xx' not found

原因定位：系统的GLIBC版本低于Bun要求，常见于较旧的Linux发行版。

解决方案：

1. 升级系统到较新的发行版
2. 或使用musl版本的Bun：curl -fsSL https://bun.sh/install | bash -s -- --musl
3. 或通过Docker使用Bun容器

案例三：权限拒绝 (Permission denied)

错误信息：error: Permission denied (os error 13)

原因定位：当前用户对安装目录或文件没有写入权限。

解决方案：

1. 避免使用sudo安装Bun，官方推荐安装在用户目录
2. 修复目录权限：chown -R $USER:$USER ~/.bun
3. 检查文件系统是否为只读模式：mount | grep $(df ~/.bun | tail -1 | awk '{print $1}')

性能对比

Bun以其出色的性能著称，特别是在JavaScript打包方面。以下是Bun与其他主流工具的打包速度对比：

从对比图中可以看出，Bun的打包速度（0.17秒）远快于Webpack 5（38.02秒）、Rollup+Terser（32.00秒）等传统工具，甚至比以速度著称的esbuild（0.30秒）还要快近一倍。

结语

通过本指南，你已经掌握了Bun运行时环境的安装、配置、版本管理和问题解决方法。Bun作为一个集多种功能于一体的现代化工具，能够显著提升JavaScript开发效率和性能。随着你对Bun的深入使用，会发现更多提升开发体验的特性和功能。

无论是前端开发、后端服务还是全栈应用，Bun都能成为你开发工具箱中的得力助手。开始你的Bun之旅吧！