Monorepo 与 pnpm workspace

为什么用 Monorepo

Skyroc Admin 把「应用」和「能力」分开：应用是薄壳，能力沉淀在数十个独立包里。这种切分天然适合 monorepo：

• 原子化提交：一次改动可以同时修改包与使用它的应用，不需要发版-安装的来回；
• 统一工具链：lint / format / test / typecheck 一套配置覆盖所有包；
• 本地实时链接：包之间用 workspace:* 引用源码，改完即时生效，无需 npm link；
• 版本一致性：通过 catalog 集中管理第三方依赖版本。

pnpm workspace

工作区由 pnpm-workspace.yaml 的 packages glob 声明：

packages:
  - 'apps/*'
  - 'packages/*'
  - 'packages/@core/*'
  - 'packages/web/*'
  - 'packages/native/*'
  - 'packages/native/ui/*'
  - 'packages/primitives/*'
  - 'packages/miniapp/*'
  - 'packages/miniapp/ui/*'
  - 'docs/*'
  - 'internal/*'

注意 glob 是逐层显式声明的（packages/@core/* 是嵌套目录，因此需要单独列出；packages/web/* 已覆盖 Web 包），避免用单个 packages/** 模糊匹配所有层级。

包之间的引用

包用 workspace:* 协议互相引用，pnpm 会把它们软链到 node_modules：

{
  "dependencies": {
    "@skyroc/utils": "workspace:*",
    "@skyroc/axios": "workspace:*"
  }
}

开发态 exports 直接指向 src/*.ts，所以改源码立即生效；发布态 publishConfig 会切到 dist。

其他关键配置

strictPeerDependencies: false # 不强制 peer 依赖（多端 peer 差异大）
ignoreWorkspaceRootCheck: true # 允许在根装一些工具依赖

overrides: # 强制全仓库统一这些版本
  '@types/react': ^19.2.7
  '@types/react-dom': ^19.2.3
  typescript: ^6.0.3

第三方依赖的版本不写在这里，而是集中在同一份文件的 catalogs: 中，见 Catalog 依赖管理。

三种包的角色

延伸阅读

• 包分层与依赖方向
• Catalog 依赖管理
• 构建体系（Turborepo 任务编排在这一篇）

Last updated on