Bun 安装和配置

Bun 是一个新兴的JavaScript运行时环境，由Jarred Sumner（前Stripe工程师）开发，旨在提供比Node.js更快速、更高效的JavaScript执行环境。它集成了包管理器、构建工具、测试框架和开发服务器，形成了一体化开发工具链，大大简化了现代JavaScript应用的开发流程。

本指南将为您提供从安装到配置的全面Bun使用指南，特别包含针对中国用户的镜像加速方案，帮助您充分利用这个高效的JavaScript运行环境。

一、Bun安装方法

根据您的操作系统，可选择以下任一安装方式：

1. macOS/Linux系统

官方推荐安装方式： curl -fsSL bun.sh/install | bash

此命令会自动：

• 下载并安装Bun二进制文件到~/.bun/bin目录
• 为zsh用户自动配置环境变量
• 创建初始配置文件~/.bunfig.toml（如果不存在）

验证安装是否成功： bun --version

2. Windows系统

官方推荐安装方式（通过PowerShell）： irm bun.sh/install.ps1 | iex

注意：

• Windows系统对Bun的支持尚不完善，部分功能可能受限
• 推荐使用WSL2（Windows Subsystem for Linux）环境进行开发，可获得更完整的功能支持
• 如果遇到执行策略限制，可先运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser更改PowerShell执行策略

3. 中国用户专用安装方式（推荐）

使用bun-cn镜像加速安装： curl -fsSL gitee.com/akirarika/b… | bash

优势：

• 通过国内npm镜像源加速下载，解决国内访问问题
• 安装后自动配置国内镜像源，加速后续依赖安装
• 与官方安装流程完全兼容

验证是否已配置国内镜像源： cat ~/.bunfig.toml | grep registry

二、环境变量配置（解决"command not found"问题）

如果安装后运行bun --version仍然提示命令未找到，很可能是环境变量未正确配置。根据您使用的shell不同，配置方式略有差异：

1. macOS/Linux的bash shell

编辑配置文件： nano ~/.bash_profile

添加以下内容（在文件末尾）： export BUN_INSTALL="HOME/.bun" export PATH="BUN_INSTALL/bin:PATH"

保存并退出：按Ctrl + O保存，再按Ctrl + X退出

使配置生效： source ~/.bash_profile

2. macOS的zsh shell（macOS Catalina 10.15及更高版本默认shell）

编辑配置文件： nano ~/.zshrc

添加以下内容： export BUN_INSTALL="HOME/.bun" export PATH="BUN_INSTALL/bin:PATH"

使配置生效： source ~/.zshrc

3. Windows系统（原生环境）

通过PowerShell配置系统环境变量： env:PATH += ";env:HOME.bunbin" [Environment]::SetEnvironmentVariable("PATH", env:PATH, "User")

注意：修改后需要重启PowerShell才能生效

4. 验证环境变量配置

运行以下命令检查Bun是否可识别： bun --version

如果仍然提示命令未找到，可尝试直接通过绝对路径执行： HOME/.bun/bin/bun --version

如果此命令成功执行，说明环境变量确实未正确配置。

三、创建项目并运行基础示例

1. 初始化新项目

创建项目目录并进入： mkdir bun quickstart && cd bun quickstart

使用bun init创建基础项目结构： bun init

按照提示选择项目模板（推荐选择"Blank"创建空项目），将生成以下基础文件：

• .gitignore：Git忽略文件
• index.ts：项目入口文件
• tsconfig.json：TypeScript配置文件
• README.md：项目说明文档
• package.json：项目配置和依赖管理文件

2. 运行基础HTTP服务器示例

编辑index.ts文件： nano index.ts

添加以下内容： const server = Bun.serve({ port: 3000, fetch(req) { return new Response("Hello from Bun!", { headers: { "Content-Type": "text/html" }, }); }, });

console.log(Server running at http://localhost:{server.port}/);

保存并退出：按Ctrl + O保存，再按Ctrl + X退出

启动服务器： bun index.ts

访问测试：

• 在浏览器中访问http://localhost:3000
• 应显示"Hello from Bun!"信息

3. 使用package.json脚本

编辑package.json文件： nano package.json

添加以下脚本（在"scripts"字段中）： { "scripts": { "start": "bun run index.ts", "dev": "bun run --watch index.ts", "build": "bun build index.ts --out dist/index.js", "test": "bun test" } }

保存并退出：按Ctrl + O保存，再按Ctrl + X退出

运行开发模式（自动重新加载）： bun dev

打包生产版本： bun build

四、中文资源与镜像加速配置

1. 配置国内镜像源（加速依赖下载）

通过bun-cn脚本自动配置（推荐）： 如果之前没有安装过bun-cn，先执行安装 curl -fsSL gitee.com/akirarika/b… | bash

如果已安装，可直接升级 curl -fsSL gitee.com/akirarika/b… | bash

手动配置镜像源：

编辑或创建配置文件： mkdir -p ~/.bun nano ~/.bun/bunfig.toml

添加以下内容： [install] registry = "registry.npmmirror.com"

[env] NODE_ENV = "development"

保存并退出：按Ctrl + O保存，再按Ctrl + X退出

验证是否生效： 安装测试包 bun add moment

查看下载源 bun install --verbose

如果显示从registry.npmmirror.com下载，说明配置成功。

2. 使用中文文档

当前可用的中文资源：

• bun-cn Gitee仓库：

  • 地址：gitee.com/akirarika/b…
  • 包含部分中文文档和国内安装工具
  • 注意：中文文档仍在建设中，尚未完全部署

• 社区翻译资源：

  • 掘金专栏《Bun入门与实践指南》：juejin.cn/post/xxx
  • CSDN博客《Bun技术评估》系列：blog.csdn.net/xxx
  • CSDN博客《Bun开发资源全攻略》：blog.csdn.net/xxx

查看中文API参考：

在项目根目录创建参考文件 echo '参照库="dom"' > dom.test.ts

五、常见问题排查与解决方案

1. "bun: command not found"问题

原因：Bun的可执行文件路径未添加到系统PATH环境变量中

解决方案：

• 重新配置环境变量：根据您的shell类型（bash/zsh），编辑对应的配置文件并添加Bun路径
• 使用绝对路径执行：HOME/.bun/bin/bun --version
• 重启终端：确保环境变量修改生效
• Windows用户：使用WSL环境或在PowerShell中手动配置PATH

2. 依赖安装缓慢或失败

原因：默认使用海外npm源，网络延迟导致

解决方案：

• 使用bun-cn脚本：自动配置国内镜像源加速安装

• 手动配置镜像源：在~/.bunfig.toml中设置registry = "registry.npmmirror.com"

• 清理缓存后重试： rm -rf node_modules bun.lockb bun install --verbose

• 使用--filter参数选择性安装： bun install --filter ./packages/ui

3. Windows环境下的路径权限问题

原因：Windows对WSL路径的访问权限控制

解决方案：

• 设置项目目录权限：

  设置目录权限

  find /path/to/project -type d -exec chmod 755 {} ;

  设置文件权限

  find /path/to/project -type f -exec chmod 644 {} ;

  设置可执行文件权限

  find /path/to/project -name "*.sh" -exec chmod 755 {} ;

• 配置wsl.conf文件（在WSL根目录）： [automount] options = "metadata,uid=1000,gid=1000,umask=22,dmask=00"

4. 服务端口被占用

原因：默认3000端口可能被其他应用占用

解决方案：

• 指定新端口： bun run --port 3001

• 自动查找可用端口：

  在项目脚本中添加此代码

  const port = 3000; const server = Bun.serve({ port: port, fetch(req) { /* ... */ }, onerror: (err) => { if (err.code === "EADDRINUSE") { console.error(Port {port} is in use, trying next port...); process.exit(1); // 可在脚本中自动重试 } } });

• 查找并终止占用进程：

  macOS/Linux

  kill (lsof -t -i:3000)

  Windows (PowerShell)

  netstat -ano | findstr :3000 taskkill /PID /F

5. 依赖冲突或版本问题

原因：不同项目或工作区依赖版本不兼容

解决方案：

• 清理依赖并重新安装： rm -rf node_modules bun.lockb bun install

• 使用--frozen-lockfile强制使用锁文件： bun install --frozen-lockfile

• 使用bun add明确指定版本： bun add react@18.2.0

• 多模型并行安装（如使用oh-my-opencode插件）：

  启用多Agent并行安装

  ultrawork bun install

6. 使用Prisma等特定框架时的兼容性问题

原因：Bun与Node.js的版本兼容性和文件系统交互机制不同

解决方案：

• 设置环境变量伪装Node.js版本：

  macOS/Linux

  BUN_IMPERSONATE_NODE_VERSION=18.18.0 bun run dev

  Windows (PowerShell)

  $env:BUN_IMPERSONATE_NODE_VERSION="18.18.0" bun run dev

• 使用兼容模式：

  在项目脚本中添加此代码

  process.env.NODE_ENV = "development"; process.env.BUNREGISTRY = "registry.npmmirror.com";

• 升级相关框架：

  检查是否有兼容性更新

  bun add pglite@latest

六、进阶配置与性能优化

1. 优化bunfig.toml配置

编辑配置文件： nano ~/.bunfig.toml

添加以下优化配置： [install] 使用pnpm风格的隔离安装模式 linker = "isolated" 并发脚本执行数量（默认CPU核心数×2） concurrentScripts = 8 禁用可选依赖安装 optional = false 启用严格模式 strict = true

[env] NODE_ENV = "development" 强制使用国内镜像源 BUNREGISTRY = "registry.npmmirror.com"

[build] 启用增量构建 incremental = true 启用缓存 cache = true

保存并退出：按Ctrl + O保存，再按Ctrl + X退出

2. 多模型并行开发（结合oh-my-opencode插件）

安装oh-my-opencode插件： 需要先安装Bun bunx oh-my-opencode install

创建多模型并行开发会话： 启动多Agent并行工作模式 bun run --watch index.ts --session multiplicative

使用特定模型执行任务： 切换到特定模型 bun run --model Kimi

3. 多项目会话管理

创建独立会话： 创建新会话 bun session new

切换会话 bun session switch

启动特定会话 bun run --session

会话隔离优势：

• 每个会话拥有独立的上下文环境
• 避免不同项目的环境变量和依赖冲突
• 支持同时运行多个开发服务器

七、总结

Bun作为新一代JavaScript运行时环境，以其超快的执行速度和一体化工具链，正在重塑前端开发体验。通过本指南，您已掌握：

• 多系统安装方法：包括macOS/Linux的bash/zsh配置和Windows的WSL适配
• 国内镜像加速方案：通过bun-cn脚本或手动配置~/.bunfig.toml使用国内npm镜像源
• 基础项目创建与运行：从bun init到HTTP服务器的完整流程
• 环境变量与路径问题解决：避免"command not found"等常见问题
• 多模型并行开发能力：结合oh-my-opencode插件实现更高效的开发流程

对于中国开发者，推荐使用bun-cn脚本进行安装，可显著提升依赖下载速度。同时，注意Windows环境下Bun的兼容性问题，建议优先使用WSL环境。

最后，Bun的生态系统仍在快速发展中，建议关注其GitHub仓库和社区动态，及时获取最新功能和优化方案。