Bun 是一个用 Rust 编写的一体化 JavaScript 工具包，它集成了运行时、打包器、测试运行器和包管理器的功能，旨在成为 Node.js 的快速、轻量级替代品。本教程将指导你在不同操作系统上完成 Bun 的安装、基本配置和项目部署。

核心概念与优势

在开始部署前，了解 Bun 的核心特性有助于你理解其价值：

  • 一体化工具：Bun 是一个单一的可执行文件 (bun)，内置了运行时、包管理器 (bun install)、测试器 (bun test)、打包器 (Bun.build) 和脚本运行器 (bun run)。这大大减少了项目中对 node_modules 的依赖和工具链的复杂性。
  • 高性能：Bun 使用 JavaScriptCore 引擎（Safari 所用）并采用 Zig 和 Rust 编写，启动速度和内存占用通常优于 Node.js。其包管理器的安装速度也远超 npm/yarn/pnpm。
  • 兼容性：Bun 旨在成为 Node.js 的即插即用替代品。它原生支持 TypeScript、JSX、ESM 和 CommonJS，并能运行大多数为 Node.js 编写的现有项目。

第一步：安装 Bun

Bun 支持 Linux (x64, arm64)、macOS (x64, Apple Silicon) 和 Windows (x64, arm64)。推荐使用官方安装脚本，这是最快捷的方式。

Linux 与 macOS
打开终端，执行以下命令：

1
curl -fsSL https://bun.com/install | bash

脚本会自动下载并安装 Bun。安装完成后，它会提示你将 Bun 的 bin 目录添加到 PATH 环境变量中（通常脚本会自动处理）。你可以重启终端或执行 source ~/.bashrc (或对应的 shell 配置文件) 来生效。

Windows
在 PowerShell (建议以管理员身份运行) 中执行：

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

其他安装方式

  • 使用 npm (如果你已有 Node.js 环境): npm install -g bun
  • 使用 Homebrew (macOS): brew tap oven-sh/bun && brew install bun
  • 使用 Docker: docker pull oven/bun

验证安装：
安装完成后，运行以下命令检查版本，以确认安装成功：

1
bun --version

第二步：升级 Bun (可选)

Bun 更新频繁，推荐定期升级以获取新特性和修复。

1
2
3
4
5
# 升级到最新稳定版
bun upgrade

# 升级到最新的开发版 (canary)
bun upgrade --canary

第三步：创建并运行你的第一个 Bun 项目

你可以用 Bun 从头开始一个新项目，也可以将其无缝引入现有的 Node.js 项目。

1. 初始化新项目
在你的项目目录中，运行：

1
bun init

这个命令会交互式地引导你创建一个 package.json 文件，并生成一个简单的 index.ts 入口文件。

2. 运行 TypeScript/JSX 文件
Bun 原生支持 TypeScript 和 JSX，无需额外配置。直接运行：

1
bun run index.ts

3. 运行 npm 脚本
如果你的 package.json 中定义了脚本（如 "start": "node server.js"），可以直接用 Bun 运行，无需修改：

1
bun run start

第四步：使用 Bun 的包管理器

Bun 的包管理器速度极快，且兼容 package.json 和 node_modules。

  • 安装所有依赖 (替代 npm install):

    1
    bun install

  • 添加生产依赖:

    1
    bun add <package-name>

  • 添加开发依赖:

    1
    bun add -d <package-name>

  • 移除依赖:

    1
    bun remove <package-name>

第五步：编写和运行测试

Bun 内置了与 Jest 风格类似的测试运行器。

  • 创建测试文件：编写如 index.test.ts 的文件，使用 describe、it/test、expect 等。

  • 运行测试：

    1
    bun test

第六步：部署 Bun 应用

Bun 应用可以像 Node.js 应用一样部署到各种云平台。

  1. 构建项目 (可选)：你可以使用 Bun.build API 将项目打包成单个文件或优化产物。

  2. 直接运行：在服务器上，只需安装 Bun，然后使用 bun run start 或 bun start.js 启动你的应用。

  3. 使用进程管理器 (如 PM2)：Bun 可以与 PM2 配合使用。

    1
    2
    # 以 PM2 运行 Bun 应用
    pm2 start bun -- start

  4. 使用 systemd (Linux)：可以创建 systemd 服务文件来管理 Bun 进程。

  5. 容器化 (Docker)：Bun 官方提供了 Docker 镜像，可以轻松构建和运行容器化的 Bun 应用。

故障排查与常见问题

  • Linux 内核版本要求：建议使用 Linux 内核 5.6 或更高版本，最低要求为 5.1。可通过 uname -r 查看版本。
  • “illegal instruction” (非法指令) 错误 (x64)：这可能是因为你的 CPU 不支持 Bun 发布版本所要求的特定指令集。请检查 Bun 文档中关于 CPU 要求的说明，或尝试从源码构建。
  • 环境变量 PATH 未更新：安装脚本执行后，如果 bun 命令找不到，可以尝试关闭并重新打开终端，或者手动将 Bun 的安装目录（通常在 ~/.bun/bin）添加到你的 PATH 中。
  • 与 Node.js 项目的兼容性：绝大多数流行的 Node.js 框架和库（如 Express、Next.js、React）都能在 Bun 中运行。如果遇到特定包不兼容，可以查阅 Bun 的官方文档或 GitHub Issues 寻找解决方案。

总的来说，Bun 作为一个新兴的 JavaScript 工具链，提供了令人印象深刻的性能和简洁的开发者体验。从现有的 Node.js 项目迁移到 Bun 通常非常平滑，你可以从 bun install 这个最快的包管理器开始体验，然后逐步过渡到使用其运行时和测试工具。开始使用 Bun，让 bun install 替代 npm install，感受速度的提升吧。