单仓库管理Skill monorepo-management

---

名称: 单仓库管理 描述: 掌握使用Turborepo、Nx和pnpm工作区管理单仓库，以构建高效、可扩展的多包仓库，并优化构建和依赖管理。在设置单仓库、优化构建或管理共享依赖时使用。

单仓库管理

构建高效、可扩展的单仓库，支持跨多个包和应用程序的代码共享、一致性工具化和原子化更改。

何时使用此技能

• 设置新的单仓库项目
• 从多仓库迁移到单仓库
• 优化构建和测试性能
• 管理共享依赖
• 实施代码共享策略
• 为单仓库设置CI/CD
• 版本控制和发布包
• 调试单仓库特定问题

核心概念

1. 为什么使用单仓库？

优势：

• 共享代码和依赖
• 跨项目的原子提交
• 一致性工具和标准
• 更容易重构
• 简化依赖管理
• 更好的代码可见性

挑战：

• 大规模构建性能
• CI/CD复杂性
• 访问控制
• 大型Git仓库

2. 单仓库工具

包管理器：

• pnpm工作区（推荐）
• npm工作区
• Yarn工作区

构建系统：

• Turborepo（大多数推荐）
• Nx（功能丰富，复杂）
• Lerna（较旧，维护模式）

Turborepo设置

初始设置

# 创建新单仓库
npx create-turbo@latest my-monorepo
cd my-monorepo

# 结构：
# apps/
#   web/          - Next.js应用
#   docs/         - 文档站点
# packages/
#   ui/           - 共享UI组件
#   config/       - 共享配置
#   tsconfig/     - 共享TypeScript配置
# turbo.json      - Turborepo配置
# package.json    - 根package.json

配置

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

// package.json（根）
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
    "clean": "turbo run clean && rm -rf node_modules"
  },
  "devDependencies": {
    "turbo": "^1.10.0",
    "prettier": "^3.0.0",
    "typescript": "^5.0.0"
  },
  "packageManager": "pnpm@8.0.0"
}

包结构

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./button": {
      "import": "./dist/button.js",
      "types": "./dist/button.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
    "lint": "eslint src/",
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
    "@repo/tsconfig": "workspace:*",
    "tsup": "^7.0.0",
    "typescript": "^5.0.0"
  },
  "dependencies": {
    "react": "^18.2.0"
  }
}

pnpm工作区

设置

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"
  - "tools/*"

// .npmrc
# 提升共享依赖
shamefully-hoist=true

# 严格的peer依赖
auto-install-peers=true
strict-peer-dependencies=true

# 性能
store-dir=~/.pnpm-store

依赖管理

# 在特定包中安装依赖
pnpm add react --filter @repo/ui
pnpm add -D typescript --filter @repo/ui

# 安装工作区依赖
pnpm add @repo/ui --filter web

# 在所有包中安装
pnpm add -D eslint -w

# 更新所有依赖
pnpm update -r

# 移除依赖
pnpm remove react --filter @repo/ui

脚本

# 在特定包中运行脚本
pnpm --filter web dev
pnpm --filter @repo/ui build

# 在所有包中运行
pnpm -r build
pnpm -r test

# 并行运行
pnpm -r --parallel dev

# 按模式过滤
pnpm --filter "@repo/*" build
pnpm --filter "...web" build  # 构建web及其依赖

Nx单仓库

设置

# 创建Nx单仓库
npx create-nx-workspace@latest my-org

# 生成应用
nx generate @nx/react:app my-app
nx generate @nx/next:app my-next-app

# 生成库
nx generate @nx/react:lib ui-components
nx generate @nx/js:lib utils

配置

// nx.json
{
  "extends": "nx/presets/npm.json",
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],
      "cache": true
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
      "!{projectRoot}/tsconfig.spec.json"
    ],
    "sharedGlobals": []
  }
}

运行任务

# 为特定项目运行任务
nx build my-app
nx test ui-components
nx lint utils

# 为受影响项目运行
nx affected:build
nx affected:test --base=main

# 可视化依赖
nx graph

# 并行运行
nx run-many --target=build --all --parallel=3

共享配置

TypeScript配置

// packages/tsconfig/base.json
{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "incremental": true,
    "declaration": true
  },
  "exclude": ["node_modules"]
}

// packages/tsconfig/react.json
{
  "extends": "./base.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "lib": ["ES2022", "DOM", "DOM.Iterable"]
  }
}

// apps/web/tsconfig.json
{
  "extends": "@repo/tsconfig/react.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

ESLint配置

// packages/config/eslint-preset.js
module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "prettier",
  ],
  plugins: ["@typescript-eslint", "react", "react-hooks"],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: 2022,
    sourceType: "module",
    ecmaFeatures: {
      jsx: true,
    },
  },
  settings: {
    react: {
      version: "detect",
    },
  },
  rules: {
    "@typescript-eslint/no-unused-vars": "error",
    "react/react-in-jsx-scope": "off",
  },
};

// apps/web/.eslintrc.js
module.exports = {
  extends: ["@repo/config/eslint-preset"],
  rules: {
    // 应用特定规则
  },
};

代码共享模式

模式1：共享UI组件

// packages/ui/src/button.tsx
import * as React from 'react';

export interface ButtonProps {
  variant?: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant = 'primary', children, onClick }: ButtonProps) {
  return (
    <button
      className={`btn btn-${variant}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

// packages/ui/src/index.ts
export { Button, type ButtonProps } from './button';
export { Input, type InputProps } from './input';

// apps/web/src/app.tsx
import { Button } from '@repo/ui';

export function App() {
  return <Button variant="primary">点击我</Button>;
}

模式2：共享实用工具

// packages/utils/src/string.ts
export function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

export function truncate(str: string, length: number): string {
  return str.length > length ? str.slice(0, length) + "..." : str;
}

// packages/utils/src/index.ts
export * from "./string";
export * from "./array";
export * from "./date";

// 在应用中用法
import { capitalize, truncate } from "@repo/utils";

模式3：共享类型

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: "admin" | "user";
}

export interface CreateUserInput {
  email: string;
  name: string;
  password: string;
}

// 在前端和后端中使用
import type { User, CreateUserInput } from "@repo/types";

构建优化

Turborepo缓存

// turbo.json
{
  "pipeline": {
    "build": {
      // 构建依赖于先构建依赖项
      "dependsOn": ["^build"],

      // 缓存这些输出
      "outputs": ["dist/**", ".next/**"],

      // 基于这些输入缓存（默认：所有文件）
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "package.json"]
    },
    "test": {
      // 并行运行测试，不依赖于构建
      "cache": true,
      "outputs": ["coverage/**"]
    }
  }
}

远程缓存

# Turborepo远程缓存（Vercel）
npx turbo login
npx turbo link

# 自定义远程缓存
# turbo.json
{
  "remoteCache": {
    "signature": true,
    "enabled": true
  }
}

单仓库的CI/CD

GitHub Actions

# .github/workflows/ci.yml
名称: CI

触发条件:
  推送:
    分支: [main]
  拉取请求:
    分支: [main]

任务:
  构建:
    运行环境: ubuntu-latest

    步骤:
      - 使用: actions/checkout@v3
        附带:
          fetch-depth: 0 # 用于Nx受影响命令

      - 使用: pnpm/action-setup@v2
        附带:
          version: 8

      - 使用: actions/setup-node@v3
        附带:
          node-version: 18
          cache: "pnpm"

      - 名称: 安装依赖
        运行: pnpm install --frozen-lockfile

      - 名称: 构建
        运行: pnpm turbo run build

      - 名称: 测试
        运行: pnpm turbo run test

      - 名称: 代码检查
        运行: pnpm turbo run lint

      - 名称: 类型检查
        运行: pnpm turbo run type-check

仅部署受影响部分

# 仅部署更改的应用
- 名称: 部署受影响应用
  运行: |
    if pnpm nx affected:apps --base=origin/main --head=HEAD | grep -q "web"; then
      echo "部署web应用"
      pnpm --filter web deploy
    fi

最佳实践

1. 一致性版本控制：在工作区中锁定依赖版本
2. 共享配置：集中ESLint、TypeScript、Prettier配置
3. 依赖图：保持无环，避免循环依赖
4. 有效缓存：正确配置输入/输出
5. 类型安全：在前端/后端之间共享类型
6. 测试策略：在包中进行单元测试，在应用中进行E2E测试
7. 文档：每个包中都有README
8. 发布策略：使用changesets进行版本控制

常见陷阱

• 循环依赖：A依赖B，B依赖A
• 幽灵依赖：使用不在package.json中的依赖
• 错误缓存输入：Turborepo输入中缺少文件
• 过度共享：共享应分开的代码
• 不足共享：跨包重复代码
• 大型单仓库：没有适当工具，构建会变慢

发布包

# 使用Changesets
pnpm add -Dw @changesets/cli
pnpm changeset init

# 创建changeset
pnpm changeset

# 版本包
pnpm changeset version

# 发布
pnpm changeset publish

# .github/workflows/release.yml
- 名称: 创建发布拉取请求或发布
  使用: changesets/action@v1
  附带:
    publish: pnpm release
  环境:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

资源

• references/turborepo-guide.md：全面Turborepo文档
• references/nx-guide.md：Nx单仓库模式
• references/pnpm-workspaces.md：pnpm工作区功能
• assets/monorepo-checklist.md：设置清单
• assets/migration-guide.md：多仓库到单仓库迁移指南
• scripts/dependency-graph.ts：可视化包依赖