1. 为什么选择 Pnpm Vite Vue 3 组合在开始搭建企业级 Monorepo 项目之前我们需要理解为什么这个技术组合如此受欢迎。Pnpm 作为包管理工具相比传统的 npm 和 yarn 有着明显的优势。它通过硬链接和符号链接的方式共享依赖不仅节省磁盘空间还能显著提升安装速度。我实测过一个包含 50 依赖的项目Pnpm 的安装速度比 npm 快了近 3 倍这在大型项目中尤其重要。Vite 则是现代前端构建工具的代表它利用浏览器原生 ES Module 特性实现了闪电般的冷启动和热更新。我在一个中型项目中做过对比Vite 的启动时间只有 Webpack 的 1/10。对于 Vue 3 项目来说Vite 提供了开箱即用的支持包括单文件组件(SFC)的快速编译和按需编译等特性。Monorepo 架构特别适合企业级项目它允许我们将多个相关项目如前端应用、组件库、文档站点等放在同一个代码仓库中管理。这样做的好处是代码共享更便捷依赖管理更统一跨项目变更更安全CI/CD 流程更简单2. 环境准备与项目初始化2.1 安装必要工具首先确保你的系统已经安装了 Node.js建议 LTS 版本和 Pnpm。如果还没安装 Pnpm可以通过以下命令全局安装npm install -g pnpm安装完成后验证版本pnpm -v2.2 创建 Monorepo 项目创建一个新目录并初始化项目mkdir vue3-monorepo cd vue3-monorepo pnpm init接下来创建 Pnpm Workspace 的核心配置文件pnpm-workspace.yamlpackages: - apps/* - packages/* - libs/*这个配置告诉 Pnpm 哪些目录下的包属于这个 Workspace。我们通常将应用放在apps/共享组件放在packages/工具库放在libs/。2.3 初始化 Git 仓库git init echo node_modules .gitignore echo .DS_Store .gitignore3. 配置基础项目结构3.1 创建第一个 Vue 3 应用在apps/目录下创建我们的第一个 Vue 3 应用pnpm create vitelatest my-app --template vue-ts cd apps/my-app pnpm install这个命令会使用 Vite 的 Vue TypeScript 模板创建一个新项目。完成后你的目录结构应该如下vue3-monorepo/ ├── apps/ │ └── my-app/ │ ├── vite.config.ts │ ├── package.json │ └── ... ├── pnpm-workspace.yaml └── package.json3.2 配置共享依赖为了让所有子项目共享相同的 Vue 和 Vite 版本我们在根目录安装这些依赖pnpm add vuelatest vitelatest -wD-w参数表示安装到 Workspace 根目录D表示作为开发依赖。4. 优化 Monorepo 配置4.1 统一 TypeScript 配置在根目录创建共享的 TypeScript 配置tsconfig.base.json{ compilerOptions: { target: ESNext, module: ESNext, strict: true, jsx: preserve, moduleResolution: node, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, baseUrl: ., paths: { /*: [apps/*/src], shared/*: [packages/*/src] } }, exclude: [node_modules] }然后在各子项目的tsconfig.json中继承这个配置{ extends: ../../tsconfig.base.json, compilerOptions: { types: [vite/client] }, include: [src/**/*.ts, src/**/*.d.ts, src/**/*.tsx, src/**/*.vue] }4.2 配置 Vite 别名为了让不同包之间可以互相引用我们需要配置 Vite 的路径别名。修改apps/my-app/vite.config.tsimport { defineConfig } from vite import vue from vitejs/plugin-vue import path from path export default defineConfig({ plugins: [vue()], resolve: { alias: { : path.resolve(__dirname, ./src), shared: path.resolve(__dirname, ../../packages/shared/src) } } })5. 创建共享组件库5.1 初始化共享包在packages/下创建我们的第一个共享组件库mkdir -p packages/shared/src cd packages/shared pnpm init修改package.json添加必要的依赖{ name: my/shared, version: 1.0.0, main: dist/index.js, types: dist/index.d.ts, scripts: { build: vite build }, dependencies: { vue: workspace:* }, devDependencies: { vite: workspace:*, vitejs/plugin-vue: ^4.0.0 } }5.2 开发第一个共享组件创建packages/shared/src/Button.vuetemplate button classshared-button slot/slot /button /template script setup langts defineProps({ type: { type: String, default: default } }) /script style scoped .shared-button { padding: 8px 16px; border-radius: 4px; cursor: pointer; } /style创建入口文件packages/shared/src/index.tsimport { App } from vue import Button from ./Button.vue export { Button } export function install(app: App) { app.component(SharedButton, Button) }5.3 配置共享包的 Vite 构建创建packages/shared/vite.config.tsimport { defineConfig } from vite import vue from vitejs/plugin-vue import { resolve } from path export default defineConfig({ plugins: [vue()], build: { lib: { entry: resolve(__dirname, src/index.ts), name: Shared, fileName: index }, rollupOptions: { external: [vue], output: { globals: { vue: Vue } } } } })6. 在应用中使用共享组件6.1 添加工作区依赖在apps/my-app/package.json中添加{ dependencies: { my/shared: workspace:* } }然后运行pnpm install6.2 使用共享组件修改apps/my-app/src/App.vuescript setup langts import { Button } from my/shared /script template Button来自共享组件的按钮/Button /template6.3 配置全局组件如果你想全局注册所有共享组件可以在main.ts中import { createApp } from vue import App from ./App.vue import { install } from my/shared const app createApp(App) app.use(install) app.mount(#app)7. 构建与优化7.1 配置构建脚本在根目录的package.json中添加构建脚本{ scripts: { build: pnpm -r run build, dev: pnpm --filter my-app run dev } }-r表示递归执行所有子项目的 build 命令--filter则指定只对某个子项目执行命令。7.2 优化构建输出对于共享组件库我们可以通过以下方式优化构建按需加载配置 Vite 输出多种格式ESM、CJS样式提取将 CSS 提取到单独文件类型声明生成完整的 TypeScript 类型定义修改packages/shared/vite.config.tsexport default defineConfig({ // ...其他配置 build: { lib: { // ...原有配置 formats: [es, cjs] }, cssCodeSplit: true, rollupOptions: { // ...原有配置 output: { assetFileNames: assets/[name][extname], entryFileNames: [format]/[name].js } } } })8. 常见问题解决在实际开发中你可能会遇到以下问题依赖提升问题Pnpm 默认不会提升依赖可能导致某些包找不到 peerDependencies。解决方案是在.npmrc中添加public-hoist-pattern[]*vue* public-hoist-pattern[]*vite*HMR 不工作确保 Vite 配置中正确设置了服务器选项server: { watch: { usePolling: true, interval: 100 } }类型找不到在共享包的package.json中确保正确设置了 types 路径{ types: dist/index.d.ts }样式隔离使用 CSS Modules 或 Scoped CSS 避免样式污染style module /* 模块化样式 */ /style这套架构已经在多个生产环境中验证过稳定性特别适合中大型 Vue 3 项目。随着项目规模扩大你还可以考虑引入 Turborepo 优化构建流水线或者 Vitest 作为统一的测试框架。
