Bun环境部署完全指南：从准备到精通

Bun作为集JavaScript运行时环境、打包工具、测试运行器和包管理器于一体的现代化工具，提供了跨平台部署解决方案。本指南将通过准备、部署、验证和进阶四个阶段，帮助您完成Bun的环境配置与版本管理，实现高效开发工作流。

一、准备阶段：环境与工具就绪

验证系统兼容性

• Linux：内核5.6+（最低5.1），安装unzip工具
• macOS：10.15+版本，支持x64/ARM架构
• Windows：10版本1809+，启用WSL2可提升体验

[!WARNING] 32位操作系统不支持Bun安装，需确认系统为64位架构

检查依赖组件

• Linux：sudo apt install unzip（Debian/Ubuntu）
• macOS：确保Xcode命令行工具已安装：xcode-select --install
• Windows：无需额外依赖，PowerShell 5.1+即可

获取安装资源

• 官方预编译二进制包（推荐）
• 包管理器渠道（npm/Homebrew/Scoop）
• Docker镜像（适合容器化部署）

[!TIP] 知识点卡片：Bun采用单一可执行文件设计，无需预先安装Node.js环境，可独立运行。

二、部署阶段：多平台安装实施

跨平台安装方法对比

操作系统	推荐安装方式	备用安装方式	适用场景
Linux/macOS	`curl -fsSL https://bun.sh/install	bash`	brew install oven-sh/bun/bun
Windows	`powershell -c "irm bun.sh/install.ps1	iex"`	scoop install bun
跨平台	npm install -g bun	Docker容器	临时测试/CI环境

执行核心安装命令

Linux/macOS一键安装

# 安装最新稳定版
curl -fsSL https://bun.sh/install | bash

# 指定版本安装示例
curl -fsSL https://bun.sh/install | bash -s "bun-v1.0.0"

Windows PowerShell安装

# 基础安装命令
powershell -c "irm bun.sh/install.ps1|iex"

# 安装特定版本
iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.0.0"

Docker容器部署

# 拉取镜像
docker pull oven/bun

# 运行交互式容器
docker run --rm -it oven/bun

[!WARNING] 使用npm安装时需确保Node.js版本≥14.0.0，且可能需要管理员权限

配置系统变量

Linux/macOS配置PATH

# 编辑shell配置文件（~/.bashrc或~/.zshrc）
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

# 使配置生效
source ~/.bashrc

Windows环境变量设置

# PowerShell命令配置用户环境变量
[System.Environment]::SetEnvironmentVariable(
    "Path",
    [System.Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.bun\bin",
    [System.EnvironmentVariableTarget]::User
)

[!TIP] 知识点卡片：PATH环境变量（系统命令搜索路径）配置后需重启终端生效，可通过echo $PATH（Linux/macOS）或echo %PATH%（Windows）验证。

三、验证阶段：安装确认与问题排查

基础功能验证

# 验证版本信息
**bun --version**

# 运行测试脚本
bun run https://bun.sh/hello.js

环境完整性检查

# 检查Bun可执行路径
which bun  # Linux/macOS
where bun  # Windows

# 验证核心功能
bun repl        # 启动交互式环境
bun install -h  # 查看包管理命令帮助

环境验证流程

[!TIP] 知识点卡片：成功安装后，Bun会自动配置Shell补全脚本，新终端中可使用Tab键补全Bun命令。

四、进阶阶段：版本管理与优化配置

版本升级与切换

# 升级到最新稳定版
**bun upgrade**

# 安装Canary版本（每日构建）
bun upgrade --canary

# 回退到稳定版
bun upgrade --stable

版本管理流程

高级配置选项

# 创建全局配置文件
touch ~/.bunfig.toml

# 配置国内镜像源示例
echo 'npmRegistry = "https://registry.npmmirror.com"' >> ~/.bunfig.toml

卸载清理流程

# curl安装方式卸载
rm -rf ~/.bun

# Homebrew卸载
brew uninstall bun

# Windows PowerShell卸载
powershell -c ~\.bun\uninstall.ps1

[!TIP] 知识点卡片：Bun配置文件支持多种格式（.bunfig.toml/.json/.js），可通过bun config命令管理配置项。

常见问题速查

安装问题

• "command not found"：检查PATH配置或重启终端
• GLIBC版本错误：尝试musl版本二进制包
• 权限问题：避免使用sudo安装，或修复目录权限

性能优化

• 设置BUN_DEBUG=1启用调试日志
• 通过bun --smol减少内存占用（牺牲部分性能）
• 使用bun upgrade --ci在CI环境中静默升级

兼容性

• Node.js模块兼容：bun install --no-save-dev
• TypeScript支持：自动识别tsconfig.json，无需额外配置
• 环境变量：Bun遵循POSIX标准，可通过.env文件加载

通过本指南，您已掌握Bun环境的完整部署流程，从系统准备到高级配置的全流程操作。Bun的单一可执行文件设计和丰富功能集，将为您的JavaScript开发工作流带来显著效率提升。