Monorepo 架构设计 - 面试完整指南

# npm/yarn 问题
node_modules/
  ├── lodash/         # 可以直接 import，但没声明
  └── your-package/

# pnpm 严格隔离
node_modules/
  ├── .pnpm/          # 所有包在这里
  └── your-package/   # 只能访问声明的依赖

// turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],  // 依赖包先构建
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "cache": false            // 测试不缓存
    },
    "lint": {}                  // 可并行执行
  }
}

# 本地缓存
.turbo/cache/
  ├── abc123def.tar.gz  # 基于 inputs hash
  └── xyz789uvw.tar.gz

# 远程缓存（Vercel/自建）
turbo run build --cache-dir=.turbo --remote-cache

# 只构建变更的包
turbo run build --filter=...@origin/main

# 只构建特定包
turbo run build --filter=@myapp/ui

# 并行构建
turbo run build test lint --parallel

优化前（串行构建）：
├── @app/admin build: 60s
├── @app/mobile build: 50s
└── @app/web build: 70s
总计：180s

优化后（Turbo并行+缓存）：
├── @app/admin build: 22s（并行）
├── @app/mobile build: 18s（并行）
└── @app/web build: 25s（并行+缓存命中部分）
总计：45s（最长任务时间）

packages/
├── shared-ui/          # L1: 基础组件库
│   ├── Button/
│   ├── Table/
│   └── Form/
├── shared-utils/       # L2: 工具函数库
│   ├── request/
│   ├── auth/
│   └── storage/
├── shared-config/      # L3: 配置库
│   ├── eslint-config/
│   ├── tsconfig/
│   └── vite-config/
└── apps/               # 业务应用
    ├── admin/
    ├── mobile/
    └── web/

// 根目录 package.json
{
  "pnpm": {
    "overrides": {
      "react": "^18.2.0",      // 强制统一版本
      "lodash": "^4.17.21"
    }
  },
  "devDependencies": {
    "@types/react": "^18.2.0"  // 全局共享
  }
}

# 检查重复依赖
pnpm list --depth=Infinity | grep "lodash"

# 依赖关系图
pnpm why react

# 清理幽灵依赖
pnpm install --shamefully-hoist=false

// ❌ 问题写法
"dependencies": {
  "@myapp/ui": "1.2.3"  // 硬编码版本
}

// ✅ 正确写法
"dependencies": {
  "@myapp/ui": "workspace:*"  // 永远指向本地最新
}

开发提交代码
   ↓
执行 pnpm changeset（生成变更记录）
   ↓
PR 合并到 main
   ↓
CI 自动创建 "Version Packages" PR
   ↓
合并后自动发布到 npm
   ↓
自动生成 GitHub Release + Changelog

// .changeset/config.json
{
  "changelog": "@changesets/changelog-github",
  "commit": true,
  "linked": [],           // 独立版本
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch"
}

# 1. 修改代码后，执行
pnpm changeset

# 2. 选择变更类型
? Which packages would you like to include?
  ✓ @myapp/ui
  ✓ @myapp/utils

? What type of change is this for @myapp/ui?
  ○ patch (bug fix)
  ○ minor (new feature)
  ● major (breaking change)

# 3. 生成 .changeset/xxx.md
---
"@myapp/ui": major
---

重构 Button 组件 API

# .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    steps:
      - uses: changesets/action@v1
        with:
          publish: pnpm release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

packages:
  # 所有 packages 下的包
  - 'packages/*'

  # 所有 apps 下的应用
  - 'apps/*'

  # 排除测试目录
  - '!**/test/**'

{
  "name": "monorepo-root",
  "private": true,
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "clean": "turbo run clean && rm -rf node_modules",
    "changeset": "changeset",
    "version": "changeset version",
    "release": "pnpm build && changeset publish"
  },
  "devDependencies": {
    "@changesets/cli": "^2.26.2",
    "turbo": "^1.10.0",
    "typescript": "^5.0.0",
    "eslint": "^8.45.0",
    "prettier": "^3.0.0"
  },
  "pnpm": {
    "overrides": {
      "react": "^18.2.0",
      "react-dom": "^18.2.0"
    },
    "peerDependencyRules": {
      "ignoreMissing": ["react", "react-dom"]
    }
  },
  "engines": {
    "node": ">=18.0.0",
    "pnpm": ">=8.0.0"
  }
}

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

module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended',
    'prettier'
  ],
  plugins: ['@typescript-eslint', 'react', 'react-hooks'],
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  settings: {
    react: {
      version: 'detect'
    }
  },
  rules: {
    'no-console': ['warn', { allow: ['warn', 'error'] }],
    '@typescript-eslint/no-explicit-any': 'warn',
    'react/react-in-jsx-scope': 'off'
  }
};

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "allowJs": false,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "composite": true,
    "incremental": true
  },
  "exclude": ["node_modules", "dist", "build"]
}

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

{
  "name": "@myapp/ui",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./Button": {
      "import": "./dist/Button.mjs",
      "require": "./dist/Button.js",
      "types": "./dist/Button.d.ts"
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "lint": "eslint src/",
    "type-check": "tsc --noEmit"
  },
  "peerDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@myapp/eslint-config": "workspace:*",
    "@myapp/tsconfig": "workspace:*",
    "@types/react": "^18.2.0",
    "tsup": "^7.2.0",
    "typescript": "^5.0.0"
  }
}

import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts', 'src/Button/index.tsx'],
  format: ['cjs', 'esm'],
  dts: true,
  splitting: false,
  sourcemap: true,
  clean: true,
  external: ['react', 'react-dom'],
  treeshake: true,
  minify: process.env.NODE_ENV === 'production'
});

{
  "name": "@myapp/admin",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint src/",
    "type-check": "tsc --noEmit"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "@myapp/ui": "workspace:*",
    "@myapp/utils": "workspace:*"
  },
  "devDependencies": {
    "@myapp/eslint-config": "workspace:*",
    "@myapp/tsconfig": "workspace:*",
    "@myapp/vite-config": "workspace:*",
    "@vitejs/plugin-react": "^4.0.0",
    "vite": "^4.4.0",
    "typescript": "^5.0.0"
  }
}

{
  "extends": "@myapp/tsconfig/react.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src"],
  "references": [
    { "path": "../../packages/shared-ui" },
    { "path": "../../packages/shared-utils" }
  ]
}

#!/usr/bin/env node
/**
 * 检查重复依赖
 */
const { execSync } = require('child_process');

const duplicates = execSync('pnpm list --depth=Infinity --json', {
  encoding: 'utf-8'
});

const parsed = JSON.parse(duplicates);
const depMap = new Map();

function traverse(deps) {
  if (!deps) return;

  Object.entries(deps).forEach(([name, info]) => {
    const key = `${name}@${info.version}`;
    if (!depMap.has(name)) {
      depMap.set(name, new Set());
    }
    depMap.get(name).add(info.version);

    if (info.dependencies) {
      traverse(info.dependencies);
    }
  });
}

traverse(parsed[0]?.dependencies);

console.log('\n🔍 检查重复依赖:\n');
let hasDuplicates = false;

depMap.forEach((versions, name) => {
  if (versions.size > 1) {
    hasDuplicates = true;
    console.log(`⚠️  ${name}: ${[...versions].join(', ')}`);
  }
});

if (!hasDuplicates) {
  console.log('✅ 没有重复依赖');
} else {
  console.log('\n💡 建议在根 package.json 中配置 pnpm.overrides 统一版本');
  process.exit(1);
}

#!/usr/bin/env node
/**
 * 快速创建新包
 */
const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

const packageName = process.argv[2];
const packageType = process.argv[3] || 'lib'; // lib | app

if (!packageName) {
  console.error('❌ 请提供包名: pnpm create:pkg my-package');
  process.exit(1);
}

const isApp = packageType === 'app';
const dir = path.join(
  process.cwd(),
  isApp ? 'apps' : 'packages',
  packageName
);

if (fs.existsSync(dir)) {
  console.error(`❌ 目录已存在: ${dir}`);
  process.exit(1);
}

// 创建目录结构
fs.mkdirSync(path.join(dir, 'src'), { recursive: true });

// 生成 package.json
const pkgJson = {
  name: `@myapp/${packageName}`,
  version: '0.0.1',
  private: isApp,
  main: isApp ? undefined : './dist/index.js',
  types: isApp ? undefined : './dist/index.d.ts',
  scripts: {
    dev: isApp ? 'vite' : 'tsup --watch',
    build: isApp ? 'vite build' : 'tsup',
    lint: 'eslint src/',
    'type-check': 'tsc --noEmit'
  },
  dependencies: {},
  devDependencies: {
    '@myapp/eslint-config': 'workspace:*',
    '@myapp/tsconfig': 'workspace:*',
    typescript: '^5.0.0'
  }
};

fs.writeFileSync(
  path.join(dir, 'package.json'),
  JSON.stringify(pkgJson, null, 2)
);

// 生成 tsconfig.json
const tsconfig = {
  extends: '@myapp/tsconfig/base.json',
  compilerOptions: {
    baseUrl: '.',
    outDir: 'dist'
  },
  include: ['src']
};

fs.writeFileSync(
  path.join(dir, 'tsconfig.json'),
  JSON.stringify(tsconfig, null, 2)
);

// 生成示例文件
const indexTs = isApp
  ? `console.log('Hello from ${packageName}');`
  : `export const hello = () => '${packageName}';`;

fs.writeFileSync(path.join(dir, 'src/index.ts'), indexTs);

console.log(`✅ 创建成功: ${dir}`);
console.log(`\n📦 下一步:`);
console.log(`  cd ${isApp ? 'apps' : 'packages'}/${packageName}`);
console.log(`  pnpm install`);
console.log(`  pnpm dev`);

name: CI

on:
  push:
    branches: [main, dev]
  pull_request:
    branches: [main, dev]

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Lint
        run: pnpm lint

      - name: Type Check
        run: pnpm type-check

      - name: Build
        run: pnpm build
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

      - name: Test
        run: pnpm test

  release:
    needs: lint-and-test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile

      - name: Create Release Pull Request or Publish
        uses: changesets/action@v1
        with:
          publish: pnpm release
          commit: 'chore: release packages'
          title: 'chore: release packages'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}