From 868f64c62f5fd70e194bd1065e412c2fed75f9c8 Mon Sep 17 00:00:00 2001 From: imbytecat Date: Mon, 26 Jan 2026 16:27:44 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E7=B2=BE=E7=AE=80=E9=87=8D?= =?UTF-8?q?=E6=9E=84=20Bun=20Catalog=20=E4=BE=9D=E8=B5=96=E7=AE=A1?= =?UTF-8?q?=E7=90=86=E6=8C=87=E5=8D=97=EF=BC=8C=E6=8F=90=E5=8D=87=E5=8F=AF?= =?UTF-8?q?=E8=AF=BB=E6=80=A7=E4=B8=8E=E4=BD=BF=E7=94=A8=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 精简并重构 Bun Catalog 依赖管理指南，突出核心概念与操作流程，优化结构提升可读性，明确使用规范与常见问题解决方案。 --- skills/bun-catalog-package/SKILL.md | 176 ++++++++++------------------ 1 file changed, 60 insertions(+), 116 deletions(-) diff --git a/skills/bun-catalog-package/SKILL.md b/skills/bun-catalog-package/SKILL.md index 5913ae8..4f262fa 100644 --- a/skills/bun-catalog-package/SKILL.md +++ b/skills/bun-catalog-package/SKILL.md @@ -1,159 +1,103 @@ --- name: bun-catalog-package -description: Bun 包管理器中使用 catalog 功能添加依赖包的标准流程指南。当用户需要在 Bun monorepo 项目中使用 catalog 功能添加或管理依赖包时使用此技能。适用于解决 Bun 不支持在子包直接安装 catalog 依赖的限制问题。 +description: Bun Catalog 依赖管理指南。在 Bun monorepo 项目中使用 catalog 功能统一管理依赖版本。 --- -# Bun Catalog 包管理流程 +# Bun Catalog 依赖管理 -## 问题背景 +## 什么是 Catalog -Bun 包管理器目前**不支持**在子包（workspace）中直接安装并自动添加到 catalog 的包。如果在子包目录执行 `bun add <包名>`，包会直接添加到子包的 `package.json`，而不会使用 catalog 引用。 +Bun Catalog 是 monorepo 中统一管理依赖版本的机制。所有版本定义在根 `package.json` 的 `catalog` 字段，子包通过 `catalog:` 协议引用。 -## 标准操作流程 +## 快速上手 -### 1. 查询包的最新版本 +### 添加新依赖（两步） ```bash -bun info <包名> +# 1. 查询最新版本 +bun info version +# 输出: 4.3.6 + +# 2. 在子包中安装 +cd apps/server +bun add @catalog: ``` -**示例**: +**前提**: 根 `package.json` 的 `catalog` 中已有该包。如果没有，先手动添加。 + +### 添加 Catalog 中不存在的包（三步） + ```bash -bun info zod -# 输出示例： -# zod@4.0.0 - TypeScript-first schema validation +# 1. 查询最新版本 +bun info version + +# 2. 在根 package.json 的 catalog 中添加 +# "catalog": { +# "": "^x.y.z" +# } + +# 3. 在子包中安装 +cd apps/server +bun add @catalog: ``` -从输出中获取包名和最新版本号（例如 `zod@4.0.0`）。 +## 常用命令 -### 2. 添加到根 package.json 的 catalog +| 命令 | 用途 | +|------|------| +| `bun info version` | 查询最新版本（仅版本号） | +| `bun info ` | 查询完整包信息 | +| `bun add @catalog:` | 在子包中安装 catalog 依赖 | +| `bun run install` | 安装所有依赖 | +| `bun outdated` | 检查过时依赖 | -在项目根目录的 `package.json` 中找到 `catalog` 字段，手动添加包及其版本： +## 文件结构示例 +**根 package.json**: ```json { "workspaces": ["apps/*", "packages/*"], "catalog": { - "react": "^18.3.1", - "typescript": "^5.0.0", - "zod": "^4.0.0" // 新增的包 + "react": "^19.0.0", + "zod": "^3.24.0", + "@tanstack/react-query": "^5.0.0" } } ``` -**注意事项**: -- 使用 `^` 前缀表示自动更新小版本（推荐） -- 也可以使用精确版本号（不加 `^`）锁定版本 - -### 3. 在子包中引用 catalog - -在需要使用该包的子包（如 `apps/api/package.json`）中，添加 catalog 引用： - +**子包 package.json** (`apps/server/package.json`): ```json { - "name": "@my-project/api", + "name": "@myapp/server", "dependencies": { - "hono": "catalog:", - "zod": "catalog:" // 引用 catalog 中的 zod + "react": "catalog:", + "zod": "catalog:" } } ``` -**格式说明**: -- 使用 `"包名": "catalog:"` 格式 -- **不需要**指定版本号，会自动使用根 `package.json` 中 catalog 定义的版本 - -### 4. 安装依赖 - -在项目根目录执行： - -```bash -bun install -``` - -Bun 会： -1. 解析 catalog 中定义的版本 -2. 将包安装到子包的 `node_modules` -3. 保持子包 `package.json` 中的 `catalog:` 引用不变 - -## 完整示例 - -假设要在 `apps/api` 中添加 `@hono/zod-validator` 包： - -```bash -# 步骤 1: 查询版本 -bun info @hono/zod-validator -# 输出: @hono/zod-validator@0.4.1 - -# 步骤 2: 编辑根 package.json -# { -# "catalog": { -# "@hono/zod-validator": "^0.4.1" -# } -# } - -# 步骤 3: 编辑 apps/api/package.json -# { -# "dependencies": { -# "@hono/zod-validator": "catalog:" -# } -# } - -# 步骤 4: 安装 -bun install -``` - -## 优势 - -使用 catalog 管理依赖的好处： - -1. **版本统一**: 所有子包使用相同版本，避免版本冲突 -2. **集中管理**: 在根 `package.json` 一处更新版本 -3. **减少重复**: 子包中只需写 `catalog:`，无需重复版本号 -4. **自动同步**: 更新 catalog 版本后，所有引用自动生效 - ## 注意事项 -- ✅ 始终在**根目录**执行 `bun install` -- ✅ catalog 定义在**根 `package.json`** -- ✅ 子包中使用 `"catalog:"` 引用（注意有冒号） -- ❌ 不要在子包目录直接 `bun add <包名>`（会绕过 catalog） -- ❌ 不要在子包 `package.json` 中写具体版本号（如 `"zod": "^4.0.0"`） +| 正确 | 错误 | +|------|------| +| `bun add zod@catalog:` | `bun add zod@latest` (绕过 catalog) | +| `"zod": "catalog:"` | `"zod": "^3.24.0"` (硬编码版本) | +| 在根目录定义版本 | 在子包定义版本 | + +## 为什么用 Catalog + +- **版本统一**: 所有子包使用相同版本，避免冲突 +- **集中管理**: 升级只需改根 `package.json` +- **减少重复**: 子包无需重复写版本号 ## 疑难排查 -### 问题：子包中显示 "catalog: 未找到" +**"catalog: 未找到"** +→ 根 `package.json` 的 `catalog` 中没有该包，先手动添加 -**原因**: 根 `package.json` 的 `catalog` 字段中没有该包 - -**解决**: 检查根 `package.json`，确保包已添加到 `catalog` 对象中 - -### 问题：安装后版本不是最新的 - -**原因**: catalog 中定义的版本过旧 - -**解决**: -1. 运行 `bun info <包名>` 查看最新版本 -2. 更新根 `package.json` 中 catalog 的版本号 -3. 重新运行 `bun install` - -## 相关命令速查 - -```bash -# 查询包信息（版本、描述等） -bun info <包名> - -# 查看已安装包的版本 -bun pm ls <包名> - -# 更新所有依赖到 catalog 定义的版本 -bun install - -# 查看 catalog 配置 -cat package.json | grep -A 20 "catalog" -``` +**版本不是最新** +→ `bun info version` 查最新版本，更新 catalog，重新 `bun run install` --- -**最后更新**: 2026-01-22 **适用版本**: Bun 1.0+