Bun CLI Cheatsheet

15 秒摘要

用 Bun 在几分钟内跑起一个 JS/TS 项目：更快的运行时 + 包管理器 + 测试 + 打包，一件套搞定。
适合：新项目、脚本工具、Web 服务本地开发；不需要手动配置 TypeScript。
复制下方 3 步命令即可在浏览器看到“Hello 01MVP”。

为什么用它（一句价值 + 3 个收益）

一句话：想以最少配置，把 JS/TS 项目在本地“跑起来并看到结果”，Bun 是最快路径。
收益：
- 快：安装依赖与执行脚本通常比 npm/yarn 更快。
- 全家桶：运行时 + 包管理 + 测试 + 构建，减少工具切换。
- TS 友好：默认支持 TS，无需额外编译步骤。
适合/不适合：适合新手起步/脚手架/小型服务；如强依赖 Node 特定特性或某些原生模块，请先验证兼容性。

3 步极速上手（复制即可运行）

步骤 1：安装

# macOS（推荐）
brew install oven-sh/bun/bun
# 或通用安装：
curl -fsSL https://bun.sh/install | bash  # Windows PowerShell: iwr bun.sh/install.ps1 | iex

步骤 2：创建最简示例

mkdir demo-bun && cd demo-bun      # 创建演示目录
bun init -y                        # 初始化（生成 package.json 等）
printf "import { serve } from 'bun';\nserve({ port: 3000, fetch: () => new Response('Hello 01MVP') });\n" > index.ts  # 最小可运行服务

步骤 3：运行并查看结果

bun run index.ts                   # 运行 TS 文件（或：bun index.ts）
# 成功判定：终端出现 "Running at http://localhost:3000"
# 浏览器打开 http://localhost:3000 显示 Hello 01MVP

命令

高频命令（覆盖 80% 场景）

初始化/创建

目的：快速创建模板项目

bun create [模板] [目录]     # 例如：bun create react ./app

依赖管理

目的：安装/新增/删除/更新依赖

bun install                   # 安装当前项目依赖（读取 package.json）
bun add [pkg]                 # 新增依赖（加 -D 安装到 devDependencies）
bun remove [pkg]              # 删除依赖
bun update                    # 更新依赖

运行脚本/文件

目的：运行 package.json scripts 或直接运行文件

bun run [script]              # 运行 scripts 中的脚本，如：bun run dev
bun run [file.ts]             # 直接运行文件，支持 TS/JS

临时执行可执行包（类似 npx）
- 目的：无需安装全局包也能执行
```
bunx [包] [参数]              # 例如：bunx eslint .
```

测试

目的：运行内置测试

bun test                      # 运行 tests；加 -w 监听

构建/打包

目的：打包前端/构建产物

bun build src/index.ts --outdir dist  # 输出到 dist；按需加 --minify 等

实用但低频的命令（有用但不是每天用）

运行并监听变更

bun --watch index.ts            # 文件变更自动重启

指定端口/环境变量

PORT=5174 bun run index.ts      # 指定端口；Windows PowerShell: $env:PORT=5174; bun run index.ts

使用镜像源（国内网络）

echo "[install]\nregistry = 'https://registry.npmmirror.com'" > bunfig.toml

最小可用配置（bunfig.toml）

只放跑通所需的关键字段；国内网络可设置镜像。

# bunfig.toml 放在项目根目录
[install]
registry = "https://registry.npmmirror.com"  # 国内镜像（可选）

常见问题（只列真高频）

每条用：症状 → 解决（带命令） → 成功判定。

安装/网络慢

症状：下载超时/连接被重置

解决：

echo "[install]\nregistry = 'https://registry.npmmirror.com'" > bunfig.toml
curl -fsSL https://bun.sh/install | bash

成功判定：安装完成无报错，bun --version 可用

版本不匹配
- 症状：命令报错/语法不支持
- 解决：
```
bun --version
brew upgrade bun || curl -fsSL https://bun.sh/install | bash
```
- 成功判定：版本满足项目要求，命令可执行
端口占用/权限问题
- 症状：Port already in use / EACCES
- 解决：
```
bun --watch index.ts --port 5174
```
- 成功判定：服务在新端口正常启动

继续深入（低频/高级用法）

官方文档：bun.sh/docs（API、打包、测试、环境变量）
模板生态：bun create [模板]（React、Next 等）

微挑战（现在动手，≤ 3 分钟）

跑通上面的 3 步；将 index.ts 返回内容改为 “Hello Bun + 01MVP”，刷新浏览器看到变化。
记录：所用命令、耗时与截图；遇到问题先查“常见问题”。

Bun CLI Cheatsheet

On this page