---
name: bun-catalog-package
description: Bun Catalog 依赖管理指南。在 Bun monorepo 项目中使用 catalog 功能统一管理依赖版本。
---

# Bun Catalog 依赖管理

## 什么是 Catalog

Bun Catalog 是 monorepo 中统一管理依赖版本的机制。所有版本定义在根 `package.json` 的 `catalog` 字段，子包通过 `catalog:` 协议引用。

## 快速上手

### 添加新依赖（两步）

```bash
# 1. 查询最新版本
bun info <package-name> version
# 输出: 4.3.6

# 2. 在子包中安装
cd apps/server
bun add <package-name>@catalog:
```

**前提**: 根 `package.json` 的 `catalog` 中已有该包。如果没有，先手动添加。

### 添加 Catalog 中不存在的包（三步）

```bash
# 1. 查询最新版本
bun info <package-name> version

# 2. 在根 package.json 的 catalog 中添加
# "catalog": {
#   "<package-name>": "^x.y.z"
# }

# 3. 在子包中安装
cd apps/server
bun add <package-name>@catalog:
```

## 常用命令

| 命令 | 用途 |
|------|------|
| `bun info <pkg> version` | 查询最新版本（仅版本号） |
| `bun info <pkg>` | 查询完整包信息 |
| `bun add <pkg>@catalog:` | 在子包中安装 catalog 依赖 |
| `bun run install` | 安装所有依赖 |
| `bun outdated` | 检查过时依赖 |

## 文件结构示例

**根 package.json**:
```json
{
  "workspaces": ["apps/*", "packages/*"],
  "catalog": {
    "react": "^19.0.0",
    "zod": "^3.24.0",
    "@tanstack/react-query": "^5.0.0"
  }
}
```

**子包 package.json** (`apps/server/package.json`):
```json
{
  "name": "@myapp/server",
  "dependencies": {
    "react": "catalog:",
    "zod": "catalog:"
  }
}
```

## 注意事项

| 正确 | 错误 |
|------|------|
| `bun add zod@catalog:` | `bun add zod@latest` (绕过 catalog) |
| `"zod": "catalog:"` | `"zod": "^3.24.0"` (硬编码版本) |
| 在根目录定义版本 | 在子包定义版本 |

## 为什么用 Catalog

- **版本统一**: 所有子包使用相同版本，避免冲突
- **集中管理**: 升级只需改根 `package.json`
- **减少重复**: 子包无需重复写版本号

## 疑难排查

**"catalog: 未找到"**
→ 根 `package.json` 的 `catalog` 中没有该包，先手动添加

**版本不是最新**
→ `bun info <pkg> version` 查最新版本，更新 catalog，重新 `bun run install`

---

**适用版本**: Bun 1.0+