当前位置：首页 > news >正文

Turborepo monorepo：别再手动管理多包了

news 2026/5/26 14:29:40

Turborepo monorepo：别再手动管理多包了

毒舌时刻

这代码写得跟网红滤镜似的——仅供参考。

各位前端同行，咱们今天聊聊 Turborepo。别告诉我你还在手动管理 monorepo，那感觉就像用算盘管理仓库——能管，但累死人。

为什么你需要 Turborepo

最近看到一个 monorepo 项目，有 20 个包，每次构建要按顺序手动执行，一个错了全部重来。我就想问：你是在写代码还是在玩多米诺骨牌？

反面教材

// 反面教材：手动管理 monorepo // package.json { "scripts": { "build": "npm run build:utils && npm run build:ui && npm run build:app", "build:utils": "cd packages/utils && npm run build", "build:ui": "cd packages/ui && npm run build", "build:app": "cd apps/web && npm run build", "test": "npm run test:utils && npm run test:ui && npm run test:app", "lint": "npm run lint:utils && npm run lint:ui && npm run lint:app" } }

# 构建过程 $ npm run build # 构建 utils... # ⏱️ 2分钟 # 构建 ui... # ⏱️ 3分钟 # 构建 app... # ⏱️ 5分钟 # 总计: 10分钟 # 如果 ui 构建失败，全部重来 # 😭😭😭

毒舌点评：这流程，构建一次要 10 分钟，你是在写代码还是在等构建？

Turborepo 的正确姿势

1. 初始化项目

# 创建 Turborepo $ npx create-turbo@latest # 或者使用示例 $ npx create-turbo@latest -e with-vite

2. 工作区配置

// pnpm-workspace.yaml packages: - 'apps/*' - 'packages/*'

my-turborepo/ ├── apps/ │ ├── web/ # Next.js 应用 │ └── docs/ # 文档站点 ├── packages/ │ ├── ui/ # UI 组件库 │ ├── utils/ # 工具函数 │ └── config/ # 共享配置 ├── package.json ├── pnpm-workspace.yaml └── turbo.json

3. Turbo 配置

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

毒舌点评：这才叫智能构建，自动处理依赖关系，并行执行任务。

4. 包配置示例

// packages/ui/package.json { "name": "@repo/ui", "version": "0.0.1", "main": "./dist/index.js", "types": "./dist/index.d.ts", "scripts": { "build": "tsup src/index.ts --format cjs,esm --dts", "dev": "tsup src/index.ts --format cjs,esm --dts --watch", "lint": "biome lint .", "clean": "rm -rf dist" }, "devDependencies": { "@repo/typescript-config": "workspace:*", "tsup": "^8.0.0", "typescript": "^5.3.0" }, "dependencies": { "react": "^18.2.0" } }

// apps/web/package.json { "name": "web", "version": "0.0.1", "scripts": { "build": "next build", "dev": "next dev", "lint": "biome lint .", "start": "next start" }, "dependencies": { "@repo/ui": "workspace:*", "@repo/utils": "workspace:*", "next": "^14.0.0", "react": "^18.2.0" } }

5. 使用 Turborepo

# 构建所有包（并行 + 缓存） $ turbo build # ⚡ 30秒后（缓存命中） # 开发模式 $ turbo dev # 运行特定包的脚本 $ turbo run build --filter=web # 运行依赖包的脚本 $ turbo run build --filter=web... # 运行被依赖包的脚本 $ turbo run build --filter=...web # 查看构建图 $ turbo run build --graph

毒舌点评：这才叫现代 monorepo 管理，智能调度、远程缓存、并行执行。

实战技巧：Turborepo 最佳实践

1. 远程缓存

# 登录 Vercel $ npx turbo login # 链接项目 $ npx turbo link # 启用远程缓存 $ turbo build --remote-only # 团队成员共享缓存，构建秒完成！

2. 环境变量管理

// turbo.json { "globalEnv": ["NODE_ENV", "API_URL"], "pipeline": { "build": { "dependsOn": ["^build"], "env": ["DATABASE_URL", "STRIPE_KEY"], "outputs": [".next/**", "dist/**"] } } }

3. 任务依赖图

// turbo.json { "pipeline": { "topo": { "dependsOn": ["^topo"] }, "//#lint": {}, "build": { "dependsOn": ["^build", "lint", "test"], "outputs": ["dist/**"] }, "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] }, "lint": { "outputs": [] }, "type-check": { "dependsOn": ["^build"], "outputs": [] } } }

4. 共享配置

// packages/typescript-config/package.json { "name": "@repo/typescript-config", "version": "0.0.1", "private": true, "files": ["base.json", "nextjs.json", "react-library.json"] }

// packages/typescript-config/base.json { "$schema": "https://json.schemastore.org/tsconfig", "compilerOptions": { "strict": true, "esModuleInterop": true, "skipLibCheck": true, "target": "ES2020" } }

// apps/web/tsconfig.json { "extends": "@repo/typescript-config/nextjs.json", "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./src/*"] } } }

5. 代码共享

// packages/utils/src/index.ts export function formatDate(date: Date): string { return date.toLocaleDateString('zh-CN'); } export function cn(...classes: (string | undefined)[]): string { return classes.filter(Boolean).join(' '); }

// apps/web/app/page.tsx import { formatDate } from '@repo/utils'; import { Button } from '@repo/ui'; export default function Page() { return ( <div> <p>今天: {formatDate(new Date())}</p> <Button>点击我</Button> </div> ); }

6. 性能优化

// turbo.json { "pipeline": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**"], "outputMode": "hash" // 只输出变更的文件 } }, "remoteCache": { "enabled": true } }

7. 常见陷阱

// 陷阱1：循环依赖 { "pipeline": { "build": { "dependsOn": ["build"] // ❌ 自己依赖自己 } } } // 正确做法 { "pipeline": { "build": { "dependsOn": ["^build"] // ✅ 依赖其他包的 build } } } // 陷阱2：忘记配置 outputs { "pipeline": { "build": { "dependsOn": ["^build"] // ❌ 没有 outputs，缓存不会生效 } } } // 正确做法 { "pipeline": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] // ✅ } } }