Monorepo 的架构选型：Turborepo、Nx、pnpm Workspace 的全维度对比

Monorepo 的架构选型：Turborepo、Nx、pnpm Workspace 的全维度对比

Monorepo 选型决策的困难在于：每个工具都能完成基础任务，但它们的核心区别体现在规模增长后才能暴露。本文从任务编排、缓存策略、依赖管理和扩展性四个维度进行对比。

一、为什么需要 Monorepo：polyrepo 的隐性成本

多仓库（polyrepo）模式在前端团队的痛点随项目规模增长逐渐显现：

• 跨仓库改动：修改一个类型定义，需要同时提交 3 个仓库的 PR，而且顺序依赖；
• 版本对齐困难：共享库的版本升级需要人工协调下游项目的升级时机；
• 代码复用受阻：因为"懒得发一个 npm 包"，团队选择在每个项目里复制粘贴工具函数。

Monorepo 不是银弹，但它是当前应对这些痛点最成熟的工程方案。

二、pnpm Workspace：最轻量的起点

pnpm Workspace 是 Monorepo 的最小实现——它只做一件事：用符号链接管理跨包的依赖关系。

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

适用场景：小型项目（2-5 个子包），对任务编排没有复杂需求。

核心限制：

• 没有任务缓存：每次pnpm build都会重新构建所有包，无论代码是否变化；
• 没有拓扑排序：pnpm -r build是并发执行，如果包 A 依赖包 B 的构建产物，需要手动控制顺序；
• 没有增量测试：运行pnpm test会跑全量测试。

/** * pnpm Workspace 的任务编排脚本示例 * 弥补 pnpm 本身缺乏的拓扑排序能力 */ interface PackageInfo { name: string; path: string; dependencies: string[]; // 工作空间内的依赖包名 } /** * 拓扑排序：确保依赖包先于消费者构建 * @param packages - 工作空间包列表 * @returns 按依赖顺序排列的包列表 */ function topologicalSort(packages: PackageInfo[]): PackageInfo[] { const sorted: PackageInfo[] = []; const visited = new Set<string>(); const visiting = new Set<string>(); function visit(pkg: PackageInfo): void { if (visited.has(pkg.name)) return; if (visiting.has(pkg.name)) { throw new Error(`循环依赖检测: ${pkg.name}`); } visiting.add(pkg.name); // 先处理所有依赖 for (const depName of pkg.dependencies) { const dep = packages.find((p) => p.name === depName); if (dep) { visit(dep); } } visiting.delete(pkg.name); visited.add(pkg.name); sorted.push(pkg); } for (const pkg of packages) { if (!visited.has(pkg.name)) { visit(pkg); } } return sorted; } /** * 按拓扑顺序执行构建 * 使用示例：node scripts/build-ordered.mjs */ async function buildAll(packages: PackageInfo[]): Promise<void> { const ordered = topologicalSort(packages); for (const pkg of ordered) { console.info(`构建: ${pkg.name}`); const { execSync } = await import('child_process'); try { execSync('pnpm build', { cwd: pkg.path, stdio: 'inherit', }); } catch (error) { console.error(`构建失败: ${pkg.name}`, error); process.exit(1); } } }

三、Turborepo：缓存与并行让 CI 时间断崖式下降

Turborepo 的核心价值可以用一句话概括：以包为粒度缓存构建结果，仅重构建变更的包。

// turbo.json 核心配置 { "pipeline": { "build": { "dependsOn": ["^build"], // 先构建依赖包 "outputs": ["dist/**", ".next/**"], // 缓存输出目录 "cache": true }, "test": { "dependsOn": ["build"], "cache": true, "outputs": [], "inputs": ["src/**", "test/**", "**/*.test.*"] }, "lint": { "cache": true, "dependsOn": [] }, "type-check": { "dependsOn": ["^build"], "cache": true } } }

Turborepo 的关键特性：

/** * 在 CI 中使用 Turborepo 远程缓存的配置封装 * 确保 CI 环境正确连接到远程缓存服务 */ interface TurboCIConfig { /** 远程缓存地址 */ cacheEndpoint: string; /** 团队令牌 */ teamToken: string; /** 是否启用远程缓存 */ remoteCacheEnabled: boolean; } /** * 生成 CI 中的 Turbo 环境变量配置 * @param config - CI 缓存配置 * @returns 环境变量键值对 */ function generateTurboEnv(config: TurboCIConfig): Record<string, string> { if (!config.remoteCacheEnabled) { console.info('远程缓存未启用，使用本地缓存'); return {}; } // 校验必填配置 if (!config.cacheEndpoint || !config.teamToken) { throw new Error( '远程缓存已启用但缺少必要配置: cacheEndpoint 和 teamToken 为必填项' ); } console.info(`远程缓存已配置: ${config.cacheEndpoint}`); return { TURBO_API: config.cacheEndpoint, TURBO_TOKEN: config.teamToken, TURBO_TEAM: 'team_2tanrui', // CI 中使用 hash 文件名确保缓存命中率 TURBO_REMOTE_CACHE_SIGNATURE: 'true', }; }

四、Nx：当项目规模超过 Turbo 的上限

Nx 与 Turborepo 的核心区别在于定位。Turborepo 是一个任务运行器，Nx 是一个构建系统。

在前端团队规模超过 20 人、子包超过 30 个时，Nx 的差异化能力开始显现：

1. 代码生成器（Generators）是 Nx 最被低估的能力。它不仅仅是create-react-app式的初始化工具，而是团队标准的程序化执行者：

/** * Nx 自定义 Generator 示例：生成标准前端页面 * 确保所有新页面遵循统一的文件结构和代码模式 */ import { Tree, formatFiles, generateFiles } from '@nx/devkit'; import * as path from 'path'; interface PageGeneratorSchema { name: string; directory: string; route: string; } /** * Nx Generator 入口函数 * 自动创建页面组件、样式文件、测试文件、路由注册 */ export default async function pageGenerator( tree: Tree, options: PageGeneratorSchema ): Promise<void> { const projectRoot = `apps/${options.directory}`; // 检查目标目录是否存在 if (!tree.exists(projectRoot)) { throw new Error( `目标目录不存在: ${projectRoot}，请确认项目已正确初始化` ); } // 使用模板文件生成标准页面结构 generateFiles( tree, path.join(__dirname, 'files'), path.join(projectRoot, 'src/pages', options.name), { ...options, tmpl: '', // 模板文件名中的 __tmpl__ 后缀会被移除 } ); // 注册路由 const routesPath = path.join(projectRoot, 'src/routes.ts'); const routesContent = tree.read(routesPath, 'utf-8'); if (!routesContent) { throw new Error(`路由文件不存在: ${routesPath}`); } const routeImport = `import { ${toPascalCase(options.name)}Page } from './pages/${options.name}';`; const routeEntry = ` { path: '${options.route}', component: ${toPascalCase(options.name)}Page },`; // 将新路由插入到已有路由数组中 const updatedContent = routesContent.replace( /(\]\s*as\s*const)/, `${routeEntry}\n$1` ); tree.write(routesPath, `${routeImport}\n${updatedContent}`); // 格式化所有生成和修改的文件 await formatFiles(tree); } /** 工具函数：将 kebab-case 转为 PascalCase */ function toPascalCase(str: string): string { return str .split('-') .map((part) => part.charAt(0).toUpperCase() + part.slice(1)) .join(''); }

2. 模块边界规则（Module Boundary Rules）是 Nx 独有的架构治理能力。它允许团队声明式定义"哪个包可以导入哪个包"，并在 lint 阶段强制执行。

3. Nx Cloud 分布式任务执行在大型 Monorepo 中意义重大——将构建任务分散到多台机器，把 CI 时间从 30 分钟压到 5 分钟。

五、总结

Monorepo 工具选型的核心决策逻辑：

三个工具不是竞争关系，而是按规模递进的梯队。选择一个工具后，不要因为它"缺某个特性"就迁移——先评估这个特性对你的团队是否真正必要。

本文工具对比数据基于 Turborepo v2.0、Nx v19、pnpm v9 版本。

资料说明

本文中的协议、版本、性能、成本和行业趋势应以可核验的一手资料为准。未标注统计口径的比例、时间表和预测仅作工程讨论，不应视为行业事实。可参考 0730 资料来源索引，并在发布前将具体来源贴到对应断言之后。