清风自叙小筑

Appearance

Next.js Monorepo — Turborepo ​

Turborepo 是 Vercel 出品的 Monorepo 管理工具，解决多项目/多包协作的场景。

什么时候需要 Monorepo ​

共享组件 + 共享工具 + 多个应用 时：

❌ 不用 Monorepo：
  每个项目一个仓库 → 共享代码靠 npm 发版 → 改一个组件要发版+升级 N 个项目

✅ 用 Monorepo：
  一个仓库管所有 → 共享代码直接 import → 改一个组件所有项目立刻生效

项目结构 ​

my-turborepo/
├── apps/
│   ├── web/              # Next.js 前台
│   │   └── package.json
│   └── admin/            # Next.js 后台
│       └── package.json
├── packages/
│   ├── ui/               # 共享 UI 组件
│   │   ├── src/Button.tsx
│   │   └── package.json
│   ├── database/         # 共享 Prisma schema
│   │   └── package.json
│   └── config-eslint/    # 共享 ESLint 配置
│       └── package.json
├── package.json           # 根 package.json
└── turbo.json             # Turborepo 配置

初始化 ​

bash
npx create-turbo@latest

turbo.json — 任务编排 ​

json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],     // 先构建依赖包
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "persistent": true,          // 持续运行
      "cache": false
    },
    "lint": {
      "dependsOn": ["^build"]      // lint 之前确保依赖已构建
    },
    "test": {}
  }
}

共享包的 package.json ​

json
// packages/database/package.json
{
  "name": "@myrepo/database",
  "version": "0.0.0",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts"
  }
}
ts
// packages/database/src/index.ts
import { PrismaClient } from '@prisma/client'
export const db = new PrismaClient()
tsx
// apps/web/app/page.tsx → 直接引用共享包
import { db } from '@myrepo/database'
const posts = await db.post.findMany()

三个核心命令 ​

bash
turbo dev          # 同时启动所有应用的 dev
turbo build        # 并行构建 + 自动处理依赖顺序
turbo lint         # 所有项目并行 lint

缓存 ​

bash
# 两次构建之间缓存中间产物
turbo build        # 第一次：全量构建
turbo build        # 第二次：命中缓存，秒级完成

缓存 key = 源码 hash + 依赖 hash，在 CI 中通过 --cache-dir=.turbo 共享。

内部包引用 ​

json
// apps/web/package.json
{
  "dependencies": {
    "@myrepo/ui": "*",         // 共享 UI
    "@myrepo/database": "*"    // 共享数据库
  }
}

* 表示 workspace 内部包，pnpm install 自动软链接到本地。

实际场景示例 ​

你的 AI 面试官项目如果用 Monorepo：

apps/
  web/           → Next.js 主站（你的 langgraph-server）
  admin/         → 后台管理
packages/
  ai/            → 共享 AI 调用逻辑（多模型路由）
  ui/            → 共享组件（聊天界面、编辑器）
  database/      → 共享 Prisma schema
  auth/          → 共享鉴权逻辑