Bun 中的目录（Catalogs）提供了一种简单的方法，在 monorepo 中的多个包之间共享通用依赖版本。与其在每个工作区包中重复指定相同的版本，不如在根 package.json 中一次性定义它们，并在整个项目中一致地引用它们。

概述

与传统的依赖管理不同（每个工作区包需要独立指定版本），目录让你可以：

1. 在根 package.json 中定义版本目录
2. 使用简单的 catalog: 协议引用这些版本
3. 只需在一个地方更改版本，即可同时更新所有包

这在大型 monorepo 中特别有用，其中数十个包需要使用相同版本的关键依赖。

如何使用目录

目录结构示例

考虑一个具有以下结构的 monorepo：

my-monorepo/
├── package.json
├── bun.lock
└── packages/
    ├── app/
    │   └── package.json
    ├── ui/
    │   └── package.json
    └── utils/
        └── package.json

1. 在根 package.json 中定义目录

在根级别的 package.json 中，在 workspaces 对象内添加 catalog 或 catalogs 字段：

{
  "name": "my-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0"
    },
    "catalogs": {
      "testing": {
        "jest": "30.0.0",
        "testing-library": "14.0.0"
      }
    }
  }
}

如果你将 catalog 或 catalogs 放在 package.json 文件的顶层，也可以正常工作。

2. 在工作区包中引用目录版本

在工作区包中，使用 catalog: 协议引用版本：

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "jest": "catalog:testing"
  }
}

{
  "name": "ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "testing-library": "catalog:testing"
  }
}

3. 运行 Bun Install

运行 bun install 以根据目录版本安装所有依赖。

Catalog 与 Catalogs

Bun 支持两种定义目录的方式：

1. catalog（单数）：一个用于常用依赖的默认目录

   "catalog": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   }

   只需使用 catalog: 引用：

   "dependencies": {
     "react": "catalog:"
   }

2. catalogs（复数）：多个命名目录用于分组依赖

   "catalogs": {
     "testing": {
       "jest": "30.0.0"
     },
     "ui": {
       "tailwind": "4.0.0"
     }
   }

   使用 catalog:<name> 引用：

   "dependencies": {
     "jest": "catalog:testing",
     "tailwind": "catalog:ui"
   }

使用目录的好处

• 一致性：确保所有包使用相同版本的关键依赖
• 维护：在一个地方更新依赖版本，而不是在多个 package.json 文件中更新
• 清晰：清楚地表明哪些依赖在你的 monorepo 中是标准化的
• 简单：不需要复杂的版本解析策略或外部工具

实际示例

这是一个更全面的 React 应用程序示例：

根 package.json

{
  "name": "react-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0",
      "react-router-dom": "^6.15.0"
    },
    "catalogs": {
      "build": {
        "webpack": "5.88.2",
        "babel": "7.22.10"
      },
      "testing": {
        "jest": "29.6.2",
        "react-testing-library": "14.0.0"
      }
    }
  },
  "devDependencies": {
    "typescript": "5.1.6"
  }
}

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "react-router-dom": "catalog:",
    "@monorepo/ui": "workspace:*",
    "@monorepo/utils": "workspace:*"
  },
  "devDependencies": {
    "webpack": "catalog:build",
    "babel": "catalog:build",
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/utils",
  "dependencies": {
    "react": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing"
  }
}

更新版本

要在所有包中更新版本，只需在根 package.json 中更改版本：

"catalog": {
  "react": "^19.1.0",  // 从 ^19.0.0 更新
  "react-dom": "^19.1.0"  // 从 ^19.0.0 更新
}

然后运行 bun install 来更新所有包。

锁文件集成

Bun 的锁文件跟踪目录版本，使得在不同环境中确保一致的安装变得容易。锁文件包括：

• 来自 package.json 的目录定义
• 每个目录依赖的解析

{
  "lockfileVersion": 1,
  "workspaces": {
    "": {
      "name": "react-monorepo",
    },
    "packages/app": {
      "name": "app",
      "dependencies": {
        "react": "catalog:",
        "react-dom": "catalog:",
        ...
      },
    },
    ...
  },
  "catalog": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    ...
  },
  "catalogs": {
    "build": {
      "webpack": "5.88.2",
      ...
    },
    ...
  },
  "packages": {
    ...
  }
}

限制和边界情况

• 目录引用必须匹配 catalog 或命名 catalogs 之一中定义的依赖
• 目录名称中的空字符串和空格将被忽略（视为默认目录）
• 目录中的无效依赖版本将在 bun install 期间无法解析
• 目录仅在工作区内可用；它们不能在 monorepo 之外使用

Bun 的目录系统提供了一种强大而简单的方法，在你的 monorepo 中保持一致性，而不会给你的工作流引入额外的复杂性。

发布

当你运行 bun publish 或 bun pm pack 时，Bun 会自动将 package.json 中的 catalog: 引用替换为解析后的版本号。发布的包包含常规的 semver 字符串， 不再依赖于你的目录定义。