去年我们团队正式切到 Monorepo 的时候我花了整整一个周末研究模板工程化。这个“从零搭建企业级 Monorepo 工程化模板”的标题看起来是技术选型问题实际上是一套标准化工作流——从初始化命令、应用创建方式到一份能跨包复用的 TypeScript 配置每一步都决定团队后续的协作效率。我基于 pnpm workspace Turborepo 这套方案完整落地过好几次踩了不少坑这篇把我认为能直接照抄的东西整理出来。如果你是一个中大型前端团队的技术负责人、基建开发者或者正在犹豫要不要把多个项目收进一个仓库的新人这篇文章都适用。我会把“初始化”怎么做、“应用”怎么建、以及共享 TypeScript 配置为什么值得单独抽出来讲清楚也会把我实际遇到过的破事一并说透。1. 方案选型与整体思路拆解1.1 为什么是 pnpm Turborepo 而不是 npm/yarn Lerna很多团队一提 Monorepo第一反应是 Lerna。Lerna 确实是最早把“多包仓库”这个概念带火的工具但它本质是一个版本管理和发布工具对 task 编排、增量构建、缓存这些工程化硬需求支持偏弱而且和 pnpm workspace 配合时需要额外手工配置。今天再搭建新模板我建议直接从 pnpm workspace 起步再叠加一层 Turborepo 做任务编排。pnpm 的核心优势在于依赖管理机制。它通过全局 store 硬链接的方式安装依赖多个项目共享同一份依赖缓存装包速度比 npm 快很多同时通过符号链接把依赖“按需”暴露给每个包天然规避了 npm 经典的“幽灵依赖”问题。这在 Monorepo 场景下尤其重要一个仓库里有几十个包如果不做严格隔离未来升级某一个依赖版本时会牵连一片。Turborepo 负责的是另一层问题任务编排和缓存。比如 web 应用构建之前必须先构建它依赖的 ui 包api 服务类型检查前也可能需要先编译 utils。Turborepo 用 pipeline 声明这些依赖关系并且用本地文件系统做缓存只要输入文件 hash 没变第二次构建直接秒出结果。这一点在 CI 上收益最明显团队十个人每天跑几十次流水线省下来的分钟数是实打实的。1.2 目录结构设计apps 与 packages 的边界模板的目录结构要尽量简单但边界必须清晰。我常用的布局是这样的monorepo-template/ ├── apps/ │ ├── web/ # 前端应用React/Vue 均可 │ └── api/ # Node 服务 ├── packages/ │ ├── ui/ # 组件库 │ ├── utils/ # 纯工具函数 │ └── config/ # 共享配置tsconfig、eslint 等 ├── package.json ├── pnpm-workspace.yaml ├── turbo.json └── tsconfig.base.jsonapps 目录放的是最终能被部署运行的应用packages 目录放的是被应用依赖的内部库。这个划分不是拍脑袋定的它解决了一个实际问题应用中不能出现相互依赖关系web 不能依赖 api反之亦然而内部库之间可以自由引用。当代码评审时看到 apps 之间的依赖基本可以判定设计出了问题。1.3 模板要解决的四类团队问题我搭建这套模板的根本目的不是追热点而是为了终结几个真实存在团队里的糟心事。第一新项目启动太慢每次都要复制老项目的 package.json、手动改配置复制多了容易漏。第二各项目 TypeScript 配置不统一一个开了 strict一个关了 noImplicitAny换项目写代码就像换语言。第三依赖版本漂移utils 包在 web 里是 1.0.1在 api 里是 1.0.5行为不一致。第四构建顺序混乱开发本地跑得通CI 上因为依赖构建顺序错了频繁挂。这套模板把以上问题全部用工程手段固定下来初始化命令统一tsconfig 通过共享 base 约束内部包统一用 workspace 协议构建顺序交给 Turborepo pipeline。团队里新人来了跑一遍文档就能开始写业务代码不需要理解所有底层细节这本身就是模板最大的价值。2. 初始化工程骨架workspace 配置与规范落地2.1 根目录初始化与 pnpm workspace 配置先创建目录并初始化 Git初始化这一步不要省略模板和 Git 历史最好在同一天开始mkdir monorepo-template cd monorepo-template git init pnpm initpnpm init 会生成一个最基础的 package.json我们需要手动改动几个关键字段。一个是 private: true避免根包被意外发布到 npm。一个是 packageManager 字段这个下面单独说。接着创建 pnpm-workspace.yaml这是整个 Monorepo 的“地图”packages: - apps/* - packages/*模式是 glob告诉 pnpm 哪些目录算作独立工作区。配置完成后在任意子包目录里执行 pnpm addpnpm 会自动识别 workspace 并安装。这里有个细节pnpm-workspace.yaml 必须在仓库根目录否则子包不会被识别最直接的排查方法就是看 pnpm 安装时有没有提示“Ignored build scripts”或者子包根本不在 dependencies 里。2.2 用 packageManager 固定包管理器版本企业级模板最怕“本地行、线上挂”而“线上挂”最常见原因就是环境不一致。比如本地用 pnpm 9CI 上用默认配置跑了 npm install锁文件完全不同依赖树就乱了。所以在根 package.json 里必须写死包管理器版本packageManager: pnpm10.4.1这个字段是新一代 Node.js 和 Corepack 的约定。团队其他人 clone 仓库后只要开启了 CorepackNode.js 自带默认开启部分环境需手动 corepack enablepnpm 版本就会自动切到 10.4.1装出来的 node_modules 和锁文件完全一致。提示初始化的那一刻建议用pnpm --version确认当前版本并且把实际版本写入 packageManager。只写pnpm10不写具体版本的Corepack 会提示找不到精确版本CI 上容易踩坑。2.3 Turborepo 任务编排与缓存策略接下来安装 Turborepo 并配置 pipeline。安装到根目录即可子包不需要重复安装pnpm add -w -D turbo根 package.json 的 scripts 里把原来那堆“在每个包里反复执行”的脚本收拢成几个统一入口scripts: { build: turbo run build, dev: turbo run dev, lint: turbo run lint, typecheck: turbo run typecheck, test: turbo run test }turbo.json 是核心我这份配置可以直接套用{ $schema: https://turbo.build/schema.json, tasks: { build: { dependsOn: [^build], outputs: [dist/**] }, typecheck: { dependsOn: [^build] }, lint: { outputs: [] }, dev: { cache: false, persistent: true } } }dependsOn 里的 ^build 表示“先构建上游依赖再构建当前包”。依赖关系图自动从 pnpm workspace 的依赖关系推导不用手工维护。outputs 声明哪些目录需要被缓存build 的产物在 dist声明了之后 Turborepo 才能做成果物缓存。dev 任务必须 persistent: true意思是进程不会自己退出且永远不要缓存 dev。2.4 工程规范ESLint、Prettier 与 Git 钩子模板工程化不只是构建代码规范也算。我用 ESLint Prettier然后靠 husky lint-staged 把检查挂在 Git commit 上。安装pnpm add -w -D eslint prettier husky lint-staged pnpm dlx husky inithusky init 会自动生成 .husky/pre-commit 文件把它改成pnpm lint-staged同时在根 package.json 里配置 lint-staged让它在每个被 Git 暂存的 .ts/.tsx 文件上跑 prettier 和 eslintlint-staged: { *.{ts,tsx,js,jsx}: [ prettier --write, eslint --fix ] }这里强调一个细节Prettier 和 ESLint 都要装到根目录并用统一的 .prettierrc 和 eslint.config.js 约束所有子包而不是让每个 app/package 自己维护一份。否则规范很容易“退化”成各写各的。如果后续有特殊 ESLint 规则比如 React hooks 检查React 应用里再单独 extends 即可。3. 创建应用与共享 TypeScript 配置3.1 创建前端应用与内部包的依赖关系应用创建可以直接用官方脚手架也可以手动搭。如果要快用 Vite 的 create 命令pnpm create vite apps/web --template react-ts但注意脚手架生成的 package.json 还是“单包”思维name 是 web 或 vite-project 这类通用名需要在 workspace 体系里改成带 scope 的命名比如 company/web。企业内部包统一使用 scope是避免包名冲突的基础。再把内部包依赖挂上注意依赖类型cd apps/web pnpm add company/ui company/utils从 workspace 内部安装依赖时pnpm 会自动把版本写成 workspace:*语义是“无论这个内部包什么版本一律用当前仓库里的源码”。打开 apps/web 的 package.json会看到dependencies: { company/ui: workspace:*, company/utils: workspace:* }这个字段也是后面做自动化发布时的重要标记。发布工具看到 workspace 协议会知道这个依赖来自仓库内部发布时替换成实际版本号。对于 Node 服务我通常不用脚手架直接手动搭。apps/api 的 package.json 保持精简开发期用 tsx 跑 TypeScript 文件构建用 tsup 打包。这样整个模板不绑定某个 Web 框架apis 可以自由选择 Express、Fastify 或者 NestJS模板层面只保证工程能力一致。3.2 共享 TypeScript 配置base extends 组合这是整个标题里“共享 TypeScript 配置”的核心。Monorepo 里最常见的 TypeScript 问题是每个包都有一份 tsconfigA 包开了 strictB 包没开A 包 moduleResolution 是 nodeB 包是 bundler。互相引用时类型对不上体验非常割裂。解决办法是在根目录维护一份 tsconfig.base.json作为所有包的“宪法”{ compilerOptions: { target: ES2022, module: ESNext, moduleResolution: Bundler, lib: [ES2022, DOM, DOM.Iterable], strict: true, noUncheckedIndexedAccess: true, exactOptionalPropertyTypes: true, esModuleInterop: true, forceConsistentCasingInFileNames: true, resolveJsonModule: true, isolatedModules: true, skipLibCheck: true, declaration: true, declarationMap: true, sourceMap: true } }关键项是 moduleResolution: Bundler。传统 node 模块解析规则对现代前端项目Vite、tsup、双格式产物已经不太友好Bundler 模式能正确处理 package.json exports 字段让内部包的 ESM/CJS 双格式识别正常。然后每个包自己的 tsconfig.json 只需要很短{ extends: ../../tsconfig.base.json, compilerOptions: { outDir: ./dist, rootDir: ./src }, include: [src] }extends 是相对路径按包所在目录层级写。这里有个很容易踩的坑extends 的路径必须能解析到文件不要省略 .json 后缀。TypeScript 有时候能自动补全但 CI 环境里的 Node 版本和本地不同还是写全为好。提示如果你用的是 VS Code配置完 tsconfig 后记得重启 TypeScript 服务按 F1 选 “TypeScript: Restart TS Server”否则编辑器可能还在用旧配置报错。3.3 路径别名与跨包源码联动共享配置解决“选项统一”路径别名解决“开发期源码联动”。内部包被应用消费的时候有两条路消费构建产物或者直接消费源码。构建产物模式适合发布源码模式适合开发调试。我的习惯是开发时走源码发布前走构建产物。做法是在基础配置里统一加 pathsbaseUrl: ., paths: { company/ui: [packages/ui/src/index.ts], company/utils: [packages/utils/src/index.ts] }配置之后apps/web 里import { Button } from company/ui会直接指向源码文件。开发过程中改了 ui 包的代码web 页面热更新立刻生效不用手动去构建一次 ui 包。但这里也要注意副作用如果在 build 阶段也只用 paths 指源码那么 tsup 打包时会把 company/ui 的代码打进产物而不是保留对 workspace 包的引用最终部署安装时会找不到 company/ui 这个包。所以生产构建前必须确保走的是产物路径。实践中我会把生产构建命令改成先turbo run build构建所有依赖再让应用打包时按 exports 指向产物。这一点依赖工具支持Vite 默认会先看 targets 的 exports 字段而 paths 优先级更高所以生产打包前把 paths 指到 dist 或者干脆移除 paths 都是可行方案。3.4 构建产物配置与发布前置检查内部库的构建我用 tsup配置简洁输出 ESM CJS 双格式顺带生成类型声明import { defineConfig } from tsup; export default defineConfig({ entry: [src/index.ts], format: [esm, cjs], dts: true, sourcemap: true, clean: true, });每个内部库的 package.json 必须明确 exports 地图这是 ESM/CJS 双格式下“能不能被正确引用”的关键{ name: company/ui, version: 0.1.0, main: ./dist/index.js, module: ./dist/index.mjs, types: ./dist/index.d.ts, exports: { .: { types: ./dist/index.d.ts, import: ./dist/index.mjs, require: ./dist/index.js } } }发布前置检查我建议在根目录加一个独立的 typecheck 脚本让它跑全仓库的类型检查。很多团队只跑 lint 不跑 typecheck导致问题都到 CI 才暴露。根 package.json 里把 typecheck 注册到 turbo 后团队只需要执行pnpm typecheckTurborepo 会自动按依赖图在所有包里跑 tsc --noEmit一旦有类型错误立刻定位到具体包。这一步没有任何技术难度但对企业级仓库价值极高至少能让一半的“奇怪报错”在提交前被拦下。4. 常见问题排查与避坑实录4.1 初始化阶段最常踩的 4 个坑第一个坑是 Corepack 未启用导致 packageManager 字段形同虚设。在部分 Linux 环境里 Node.js 安装方式不同Corepack 默认禁用执行 pnpm 相关命令时直接报ERR_PNPM_NO_GLOBAL_BIN_DIR或者提示版本不符。解决方式是确认安装后执行corepack enable并且在文档里写清楚这属于环境准备的一部分。第二个坑是 package.json 里没有 private 字段。根包一旦没标记 private后续执行 pnpm publish 时可能把整个仓库根目录当包发布出去这是灾难性的。所以初始化后第一件事就是补 private: true。第三个坑是在子包里单独安装了本来应该在根目录的构建工具。比如 apps/web 里自己装了 tsup但 packages/ui 没有会导致“web 能构建但 ui 不能构建”这种割裂状态。内部包需要什么工具统一在根目录用-w安装除非某个包有完全独立的特殊需求。第四个坑是忽略 .gitignore。node_modules、dist、.turbo 这些目录如果不进 .gitignore会把整个仓库体积撑爆而且 Turborepo 的缓存目录 .turbo 进了 Git 以后CI 上的缓存策略会乱掉。我的模板 .gitignore 至少包含这几项node_modules/ dist/ .turbo/ *.log4.2 共享配置引发的“幽灵错误”共享 tsconfig 最神奇的一个坑是明明本地代码没错但 CI 上 TypeScript 报错仔细一看报错来自 node_modules 里的某个类型声明。原因是没有开 skipLibCheckTypeScript 默认会检查所有 node_modules 里 .d.ts 文件的类型这些错误往往来自第三方库自身的声明问题和我们代码无关。在我的基础配置里已经加了 skipLibCheck: true没加的话第一个“幽灵错误”大概率出现在某个内部包的 dist 目录残留。之前也遇到过一个经典问题子包的 dist 目录进了 Git.gitignore 没写好导致应用开发时引用的是旧产物而不是当前源码修改了源码却看不到效果排查了半天才发现是 Git 里残留的 dist 在作怪。另一个共享配置的坑是 declaration declarationMap 同时开启后部分构建工具对 sourcemap 路径解析不友好堆栈信息会指向 ts 源码而调试器找不到文件。这个排查起来特别耗时实际上需要检查的是 package.json 的 exports 配置是否同时声明了 source 字段以及构建工具是否开启 sourcemap 支持。4.3 缓存与增量构建的陷阱Turborepo 缓存是效率利器但配置不好会带来“缓存命中了错误结果”的隐患。我遇到过一次改了 packages/ui 的代码重新执行 pnpm build结果 apps/web 的构建依然是旧版本。排查下来发现原因在于 apps/web 的构建依赖声明写错了pipeline 里漏了 dependsOn [^build]Turborepo 不会自动推导“应用构建依赖内部包构建”的完整链条。这也是为什么我把 build 的 dependsOn 写成 ^build这里面的 ^ 不是万能药它代表“直接依赖的那些包要先构建”但间接依赖的构建顺序需要靠 Turbo 的依赖图自动解析前提是 workspace 依赖关系本身是完整的。还有一个实际项目里很容易忽略的变量环境变量参与缓存。如果你的构建脚本里读取了 .env 文件里的值而 turbo.json 没有声明 env 列表那么更换环境变量后执行构建Turborepo 可能直接命中旧缓存输出导致线上产物还是旧配置。解决办法是在 turbo.json 的 build 任务里声明env: [NODE_ENV, API_BASE_URL]只要这些值有变化缓存自动失效重新构建。提示调试“为什么缓存没更新”时可以直接执行turbo run build --force绕开缓存全量重跑能在几分钟内确认是代码问题还是缓存策略问题。个人体会这套模板最值钱的地方不是安装了多少工具而是把每个包的 tsconfig、构建命令、依赖协议都统一成了一个标准。开发一个内部包其实就是“创建目录、写 src、继承 base、跑 turbo”不需要每次重新决策。我后来复盘时发现团队在新仓库里从初始化到跑起第一个内部包平均时间从原来的两天缩短到半小时这个收益比任何单个工具都大。如果你接下来要落地这套方案我建议从“小规模”开始先收两个项目进仓库搭好 base 配置和 pipeline跑通一次完整的 build typecheck。等团队适应了再逐步把更多项目迁入不要一开始就想把几十个项目塞进来。Monorepo 是一个持续演进的过程模板给的是稳定的地基后续无论怎么加包、加应用地面都不会塌。