Files

imbytecat 868f64c62f refactor: 精简重构 Bun Catalog 依赖管理指南，提升可读性与使用规范

- 精简并重构 Bun Catalog 依赖管理指南，突出核心概念与操作流程，优化结构提升可读性，明确使用规范与常见问题解决方案。

2026-01-26 16:27:44 +08:00

2.3 KiB

Raw Blame History

name, description

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

Bun Catalog 依赖管理

什么是 Catalog

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

快速上手

添加新依赖（两步）

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

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

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

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

# 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:

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

子包 package.json (apps/server/package.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+

2.3 KiB Raw Blame History Unescape Escape