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/shared/*'
  - 'packages/web/*'
  - 'packages/web/ui/*'
  - 'packages/native/*'
  - 'packages/native/ui/*'
  - 'packages/primitives/*'
  - 'packages/miniapp/*'
  - 'packages/miniapp/ui/*'
  - 'docs/*'
  - 'internal/*'

注意 glob 是逐层显式声明的（packages/@core/* 与 packages/web/ui/* 各算一层），因为目录有嵌套，单个 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

三种包的角色

类型	目录	是否发布	例子
应用	`apps/*`	否	`skyroc-admin`
能力包	`packages/**`	多数可发布（`@skyroc/*`）	`@skyroc/axios`、`@skyroc/web-ui`
内部配置	`internal/*`	否（`private: true`）	`@skyroc/tsconfig`、`@skyroc/config`