Bun 全功能 JavaScript 工具链实战指南

Bun 是一个集 JavaScript 运行时环境、打包工具、测试运行器和包管理器于一体的现代化工具链。其核心优势在于极致的性能表现和简化的开发流程，能够显著提升前端开发效率。本文将系统介绍 Bun 的环境准备、多平台安装、配置验证、版本管理及问题排查的完整流程。

一、准备：环境与工具检查

在开始安装 Bun 之前，需要确保系统满足基本运行要求并准备必要的依赖工具。

1.1 系统要求验证

Bun 作为独立可执行文件发布，但仍需确保操作系统满足以下最低要求：

• Linux：内核版本 5.1 或更高（推荐 5.6+），glibc 2.28+ 或 musl libc
• macOS：10.15 (Catalina) 或更高版本
• Windows：Windows 10 1809 或更高版本，需启用 WSL2 或使用原生 Windows 版本

💡 重要提示：Linux 用户需确保已安装 unzip 工具，可通过以下命令安装：

# Debian/Ubuntu 系统
sudo apt update && sudo apt install unzip -y

# Fedora/RHEL 系统
sudo dnf install unzip -y

1.2 网络环境准备

Bun 安装过程需要访问互联网下载必要资源，请确保：

• 网络连接稳定
• 必要时配置好代理服务器
• 防火墙允许访问 bun.sh 相关域名

二、实施：多平台安装与配置

Bun 提供多种安装方式，可根据操作系统和使用习惯选择最适合的方案。

2.1 主流安装方法

2.1.1 命令行一键安装（推荐）

适用场景：个人开发环境、快速尝鲜、CI/CD 环境部署

Linux/macOS 用户使用 curl：

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

Windows 用户使用 PowerShell：

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

安装特定版本：

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

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

2.1.2 包管理器安装

适用场景：已熟悉系统包管理器、需要系统级安装

Homebrew (macOS/Linux)：

brew install oven-sh/bun/bun

Scoop (Windows)：

scoop install bun

npm/yarn (跨平台)：

npm install -g bun
# 或
yarn global add bun

2.1.3 Docker 容器化安装

适用场景：隔离环境测试、容器化部署

# 拉取镜像
docker pull oven/bun

# 运行交互式 shell
docker run --rm -it --init oven/bun sh

# 运行单个命令
docker run --rm --init oven/bun bun --version

2.2 环境变量配置

安装完成后，需要确保 Bun 的可执行路径已添加到系统 PATH 中。

2.2.1 Linux/macOS 配置

根据使用的 shell，在对应的配置文件（.bashrc、.zshrc 等）中添加：

export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

使配置生效：

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

2.2.2 Windows 配置

通过 PowerShell 配置用户环境变量：

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

注意：Windows 环境变量配置后需要重启终端或注销重新登录才能生效。

2.3 安装验证

完成安装后，通过以下命令验证：

bun --version

成功安装会显示版本号，如 1.0.2。若提示 "command not found"，需检查 PATH 配置是否正确。

三、进阶：版本管理与优化

掌握 Bun 的版本管理和高级配置，能够更好地适应不同项目需求。

3.1 版本控制策略

3.1.1 版本选择建议

• 稳定版：适合生产环境和正式项目，通过常规安装流程获取
• Canary 版：包含最新特性，适合测试和开发，通过以下命令安装：

  bun upgrade --canary
  

• 特定版本：用于保持项目依赖一致性，安装方法参见 2.1.1 节

3.1.2 版本升级与回退

升级到最新稳定版：

bun upgrade

回退到稳定版（从 Canary 版）：

bun upgrade --stable

包管理器用户升级：

# Homebrew
brew upgrade bun

# Scoop
scoop update bun

3.2 高级配置技巧

3.2.1 配置文件优化

Bun 支持通过 bunfig.toml 进行全局或项目级配置：

# 全局配置：~/.bun/bunfig.toml
[install]
production = true
frozen-lockfile = true

[test]
coverage = true

3.2.2 自定义安装路径

如需指定安装路径，可设置 BUN_INSTALL 环境变量：

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

# Windows
$env:BUN_INSTALL="C:\tools\bun"; irm bun.sh/install.ps1|iex

四、问题解决与维护

4.1 常见安装问题排查

4.1.1 权限问题

症状：安装过程中出现 "Permission denied" 错误

解决方法：

# 不要使用 sudo 安装，而是设置正确的目录权限
sudo chown -R $USER:$USER ~/.bun

4.1.2 GLIBC 版本不兼容

症状：运行 bun 时提示 "GLIBC_2.xx not found"

解决方法：

• 使用 musl 版本二进制文件
• 升级系统到较新的发行版
• 考虑使用 Docker 版本

4.2 卸载与数据清理

如需完全卸载 Bun，根据安装方式选择以下方法：

4.2.1 手动安装方式卸载

# Linux/macOS
rm -rf ~/.bun
# 同时删除 .bashrc/.zshrc 中的相关配置

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

4.2.2 包管理器卸载

# Homebrew
brew uninstall bun

# Scoop
scoop uninstall bun

# npm
npm uninstall -g bun

数据清理提示：除了程序文件外，Bun 还会在以下位置存储数据，如需彻底清理可一并删除：

• ~/.bun-cache：缓存目录
• 项目中的 bun.lockb 文件

4.3 获取帮助与支持

遇到问题时，可通过以下途径获取帮助：

1. 查看官方文档：docs/
2. 检查常见问题：docs/guides/
3. 项目源码仓库：通过 git clone https://gitcode.com/GitHub_Trending/bu/bun 获取完整源码和 Issue 跟踪

通过本文的指南，您应该能够顺利完成 Bun 的安装配置并解决常见问题。Bun 作为新兴的 JavaScript 工具链，持续快速发展，建议定期关注官方更新以获取最新特性和改进。