Monorepo 协作

核心配置文件

文件	作用
pnpm-workspace.yaml	workspace 包路径、catalog 统一版本、allowBuilds
turbo.json	构建依赖图：build 时先执行依赖包的 ^build
根 package.json	编排脚本、packageManager: pnpm@11.5.2
.npmrc	registry / 认证（pnpm 11 下非认证项应迁到 workspace yaml）
pnpm-lock.yaml	全仓单一锁文件

pnpm Catalog（依赖版本统一）

外部依赖版本集中在 pnpm-workspace.yaml 的 catalog 中声明，子包用 "catalog:" 引用：

catalog:
  vue: ^3.5.35
  vite: ^8.0.16
  typescript: ~6.0.3
  element-plus: ^2.9.11
  # ...

{
  "dependencies": {
    "vue": "catalog:",
    "element-plus": "catalog:"
  }
}

升级流程：只改 pnpm-workspace.yaml 中 catalog 版本 → 根目录执行 pnpm install。

mobile 独立 catalog

uni-app 受生态限制（Vite 5、TypeScript 4.9），与 web/desktop 不可混用，使用命名 catalog：

catalogs:
  mobile:
    vite: 5.2.8
    typescript: ^4.9.4
    # @dcloudio/* ...

mobile 的 package.json 写 "vite": "catalog:mobile"。

共享 TypeScript 配置

主栈（web / desktop / admin / shared）的 tsconfig 统一继承 packages/tsconfig/：

文件	用途
base.json	严格模式、ES2020、bundler 解析
vue-app.json	Vue 应用（extends @vue/tsconfig）
node.json	vite.config.ts 等 Node 脚本
lib.json / lib-dom.json	纯 TS 共享库（是否含 DOM）
vue-lib.json	Vue 组件库（components）

mobile 仍使用 catalog:mobile 的 @vue/tsconfig@0.1.x，不继承主栈 vue-app.json。

子包只保留 paths、include 等本地差异，避免各写一套 compilerOptions。

Lint / Format（ESLint 9 + Prettier）

路径	说明
packages/eslint-config	共享 ESLint flat 规则（lib / vue-app / node）
.prettierrc / .editorconfig	全仓格式约定
.vscode/settings.json	保存时 Prettier + ESLint 修复

根目录命令：

pnpm lint          # turbo 各包 eslint / dotnet build
pnpm lint:fix      # eslint --fix
pnpm format        # prettier --check
pnpm format:fix    # prettier --write（受 .prettierignore 约束）

mobile 使用 catalog:mobile 工具链，ESLint 仅扫 src/** 且关闭 type-aware 规则。

workspace 与 peer

协议	用途
workspace:^	内部包（types、admin、auth…）
catalog:	外部依赖统一版本
peerDependencies	共享库声明「宿主需提供 vue / element-plus」，见 admin 包

workspace 依赖

子包通过 workspace:^ 互相引用：

"@xichen-full-stack/types": "workspace:^"

pnpm 会链接到 packages/shared/types，改源码后 consumer 立即感知（TS 包需 build 出 dist）。

Turbo pipeline

{
  "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
  "dev": { "cache": false, "persistent": true }
}

执行 pnpm build 时，会先 build 所有被依赖的 shared 包，再 build web/desktop 等。

根目录 pnpm run clean 仅执行各子包 turbo run clean（删除 dist），不会删除 node_modules。

包发现范围

packages:
  - "packages/*"
  - "packages/shared/*"

包含：web、desktop、mobile、device-agent、server-java、server-python、shared 下所有子包。

packages/device-agent 虽在 packages/* 下，但使用 C# / dotnet，不纳入 Turbo build pipeline；通过根脚本 device-agent:dev / device-agent:build 编排。

Java / Python 与 Turbo

后端使用 Maven / pip，通常 不 纳入 Turbo build pipeline，独立启动：

pnpm --filter @xichen-full-stack/server-java dev

Electron 与 pnpm 11

postinstall 与镜像

• allowBuilds.electron: true — 允许 electron postinstall 下载二进制
• pnpm 11 不再把 .npmrc 里的 ELECTRON_MIRROR 传给 postinstall 脚本
• Electron 二进制下载须设置系统/Shell 环境变量（与 registry 镜像无关）：

# Windows PowerShell（当前会话）
$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
$env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
pnpm install

仅开发 Web、暂不跑 Desktop 时可 pnpm install --ignore-scripts，之后需要 Desktop 再 pnpm rebuild electron。

monorepo 布局

.npmrc 中 node-linker=hoisted、shamefully-hoist 等 pnpm 专属项，pnpm 11 建议逐步迁到 pnpm-workspace.yaml（参见 pnpm 11 迁移说明）。

相关文档

• 包职责对照
• 构建与部署
• 环境变量
• 常见问题