104 lines
2.3 KiB
Markdown
104 lines
2.3 KiB
Markdown
---
|
||
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+
|