forked from agents/opencode
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+
|