Bun 新手入门指南

介绍

Bun 是一个 超级快的 JavaScript/TypeScript 运行时，它不只是比 Node.js 快，还把包管理、测试、打包等功能全部打包到一个工具里。

https://bun.com/

Bun 到底是什么？它能取代 Node.js 吗？

简单来说，Bun 的目标就是成为 Node.js 的更快替代品（drop-in replacement）。它兼容大部分 Node.js 的 API 和 npm 包。

Bun 的核心优势：

• 启动和运行超快：比 Node.js 快 3 倍左右，冷启动几乎瞬间完成。
• 安装依赖飞快：bun install 比 npm install 快 10-30 倍。
• 零配置支持 TypeScript 和 JSX：写 TS 文件直接运行，不用额外配置。
• All-in-one：内置包管理、测试运行器、打包工具，不需要再学一堆额外命令。
• 兼容性强：Bun 可以直接运行绝大多数 Node.js 项目（Express、Next.js 等流行框架基本没问题）。
• 最棒的一点：Bun 是一个独立的工具，完全不需要先安装 Node.js！

Bun 是一个独立的（standalone）二进制文件，它不需要依赖 Node.js 就能工作。

也就是说，即使你的电脑上从来没有装过 Node.js，你也能直接用 Bun 创建、安装依赖、运行项目。这对第一次接触 JavaScript 后端的新手特别友好。

Bun 可以取代任意 Node.js 版本吗？

答案是不能完全取代任意 Node.js 版本，但在 2026 年 3 月的当前情况（Bun 1.3.x 版本），Bun 已经可以取代大多数常见 Node.js 项目和 Node.js v20~v23 的绝大部分功能。它非常接近 “drop-in replacement”（直接替换），但还不是 100% 完美，尤其在一些边缘场景。

• Bun 的目标是成为 Node.js 的 drop-in replacement（直接替换），它实现了 超过 95% 的 Node.js API。
• 官方文档明确表示：它针对 Node.js v23 进行了大量测试，流行框架（如 Express、Next.js、Fastify、NestJS）和大多数 npm 包都能直接运行，几乎不用改代码。
• 常见模块（如 fs、path、http、crypto、buffer、events 等）已经 完全或接近完全实现。
• 你可以直接用 bun run、bun install、bun test 来运行很多原本用 Node.js 的项目，速度更快、启动更快、内存占用更低。

对于新项目或现代技术栈（TypeScript、React、Next.js、Express 等），Bun 已经可以完全取代 Node.js。

什么情况下 Bun 不能 完全取代 Node.js？

虽然兼容性已经很强，但还有以下 少数情况 可能出问题：

• 原生插件（Native Addons）：依赖 C++ 绑定的 npm 包（如旧版的 bcrypt、sharp、better-sqlite3、canvas 等），可能出现兼容问题、崩溃或性能差异。Bun 虽然在不断改进 Node-API 支持，但不是所有预编译二进制都能完美工作。
• 极少数依赖 Node.js 内部实现细节 的老旧或 niche（小众）包。
• 某些特定 Node.js 版本的行为差异：如果你项目专门针对某个老 Node 版本（如 Node 14/16）的怪异行为，或使用了非常新的实验性 API，Bun 可能无法 100% 复现。
• 企业级极端稳定需求：大型遗留系统、需要长期 LTS 支持、或依赖特定 Node.js 安全补丁的场景，Node.js 仍然更“保险”。

如果你的项目用了某些老旧的原生插件（C++ 绑定的包），导致兼容性问题。这时可以混合使用：开发用 Bun，遇到问题再切回 Node.js。

在 macOS 上安装 Bun

打开你的 终端（Terminal），直接复制下面这条命令：

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

安装完成后，刷新一下环境：

echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

验证是否安装成功：

bun --version

看到版本号就说明成功了！

你也可以用 Homebrew 安装：

brew install oven-sh/bun/bun

Bun 的常用命令

• bun install —— 安装项目依赖（代替 npm install）
• bun add 包名 —— 添加依赖包（加 --dev 是开发依赖）
• bun run dev 或 bun run start —— 运行 package.json 中的脚本
• bun index.ts —— 直接运行单个文件（支持 .js 和 .ts）
• bun test —— 运行测试（类似 Jest）
• bun build ./app.tsx --outdir=dist —— 打包项目
• bun upgrade —— 更新 Bun 到最新版本

Bun 的命令设计得很友好，和 npm 很像，上手几乎零成本。

如何安全测试 Bun 是否能取代你的 Node.js 项目？

在你的终端里，推荐这样操作（增量尝试，不会破坏原有 Node.js）：

1. 进入你的项目目录：

   cd 你的项目文件夹
   

2. 用 Bun 安装依赖（会生成 bun.lockb，同时兼容 node_modules）：

   bun install
   

3. 尝试运行你的启动脚本：

   bun run dev     # 或 bun run start
   

4. 如果是测试项目：

   bun test
   

如果报错：

• 先更新 Bun 到最新版：bun upgrade
• 检查具体错误，很多时候是某个 native 包问题，可以尝试换成 Bun 原生替代方案（比如用 bun:sqlite 代替 better-sqlite3）。
• 最坏情况：继续用 node 运行那个有问题的脚本，Bun 只负责包管理和测试。

建议

• 新项目：直接用 Bun 起步，强烈推荐！体验会好很多。
• 现有 Node.js 项目：先用 bun install + bun run 测试一下，大概率能直接跑通。如果有问题，再逐步替换。
• 不想冒险：可以混合使用 —— 用 Bun 做包管理（bun install 超快）和开发命令，用 Node.js 做最终生产运行（很多团队目前是这样过渡的）。