# 管理后台 - Bun 使用指南

## 🥖 Bun 简介

Bun 是一个极速的 JavaScript 运行时和包管理器，专为现代前端开发而设计。

### 主要优势
- ⚡ **极速安装**: 比 npm 快 2-3 倍
- 🔧 **内置工具**: 打包器、测试运行器、转译器
- 🎯 **高兼容性**: 100% 兼容 Node.js API
- 💾 **内存效率**: 更低的内存占用
- 📦 **原生支持**: TypeScript、JSX 无需配置

## 🚀 快速开始

### 安装 Bun
```bash
# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows (使用 WSL)
curl -fsSL https://bun.sh/install | bash

# 验证安装
bun --version
```

### 项目初始化
```bash
# 进入项目目录
cd admin/

# 安装依赖
bun install

# 启动开发服务器
bun run dev
```

## 📋 常用命令

### 包管理
```bash
# 安装所有依赖
bun install

# 安装特定包
bun add react
bun add -d typescript  # 开发依赖

# 移除包
bun remove package-name

# 更新依赖
bun update

# 清理缓存
bun pm cache rm
```

### 脚本运行
```bash
# 开发服务器
bun run dev
bun dev  # 简写

# 构建生产版本
bun run build

# 类型检查
bun run type-check

# 代码检查
bun run lint

# 测试
bun run test
bun test  # 简写
```

### 高级功能
```bash
# 直接运行 TypeScript 文件
bun run src/index.ts

# 安装并运行包 (类似 npx)
bunx create-react-app my-app
bunx vite

# 查看依赖树
bun pm ls

# 安全审计
bun audit
```

## 🔧 配置文件

### package.json 配置
```json
{
  "name": "photography-admin",
  "packageManager": "bun@latest",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  }
}
```

### bun.lockb 文件
- Bun 使用二进制锁文件 `bun.lockb` 而不是 `package-lock.json`
- 体积更小，解析更快
- 自动生成，不需要手动编辑
- 确保团队间依赖版本一致

### .bunfig.toml 配置 (可选)
```toml
# 项目根目录下的 .bunfig.toml
[install]
# 使用特定的注册表
registry = "https://registry.npmjs.org/"

# 配置缓存
cache = true

# 安装时显示进度
progress = true

[dev]
# 开发服务器配置
port = 3000
```

## 📊 性能对比

### 依赖安装速度
```bash
# 测试项目: photography-admin (40+ 依赖)
npm install     ~45 秒
yarn install    ~35 秒  
pnpm install    ~25 秒
bun install     ~8 秒   # 🏆 最快!
```

### 构建速度
```bash
# React + TypeScript + Vite 项目
npm run build   ~25 秒
yarn build      ~23 秒
bun run build   ~15 秒  # 🏆 最快!
```

### 内存占用
```bash
# 开发服务器运行时内存使用
Node.js + npm   ~180 MB
Node.js + yarn  ~165 MB
Bun            ~120 MB  # 🏆 最省内存!
```

## 🔄 迁移指南

### 从 npm 迁移
```bash
# 1. 删除旧的锁文件和 node_modules
rm package-lock.json
rm -rf node_modules/

# 2. 使用 bun 安装依赖
bun install

# 3. 更新 package.json
echo '"packageManager": "bun@latest",' >> package.json
```

### 从 yarn 迁移
```bash
# 1. 删除 yarn 相关文件
rm yarn.lock
rm -rf node_modules/

# 2. 安装依赖
bun install

# 3. 更新脚本命令
# 将 yarn dev 改为 bun run dev 或 bun dev
```

## 🛠️ Makefile 集成

项目已配置 Makefile 来简化 Bun 命令：

```bash
# 快速启动
make quick      # bun install + bun run dev

# 开发相关
make dev        # bun run dev
make build      # bun run build
make check      # lint + type-check + test

# 项目管理
make clean      # 清理构建文件
make status     # 查看项目状态
make audit      # 安全审计
```

## 🐛 常见问题

### Q: bun.lockb 文件很大？
A: 这是正常的，bun.lockb 是二进制文件，包含了完整的依赖图信息，虽然看起来大但解析极快。

### Q: 某些包在 Bun 下不工作？
A: Bun 与 Node.js 高度兼容，但少数包可能有兼容性问题。可以使用 `bun --bun` 强制使用 Bun 运行时。

### Q: 如何在 CI/CD 中使用 Bun？
A: 项目已配置使用 `oven-sh/setup-bun@v1` action，自动设置 Bun 环境。

### Q: 团队成员必须都使用 Bun 吗？
A: 不必须。Bun 可以读取 `package-lock.json`，npm/yarn 也能处理 Bun 项目，但推荐统一使用 Bun 以获得最佳性能。

## 📚 参考资料

- [Bun 官方文档](https://bun.sh/docs)
- [Bun GitHub 仓库](https://github.com/oven-sh/bun)
- [Bun vs Node.js 性能对比](https://bun.sh/blog/bun-v1.0)
- [Bun 包管理器指南](https://bun.sh/docs/cli/install)

## 🎯 最佳实践

1. **依赖管理**: 定期运行 `bun outdated` 检查过时依赖
2. **锁文件**: 始终提交 `bun.lockb` 到版本控制
3. **脚本优化**: 利用 Bun 的速度优势，多运行类型检查和测试
4. **CI/CD**: 在 CI 中使用 `--frozen-lockfile` 确保一致性
5. **团队协作**: 在 README 中说明项目使用 Bun

---

🥖 **享受 Bun 带来的极速开发体验吧！**