基于 Pnpm Workspace 与 Vite 搭建 Vue 3 企业级 Monorepo 项目

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 -v

2.2 创建 Monorepo 项目

创建一个新目录并初始化项目：

mkdir vue3-monorepo && cd vue3-monorepo pnpm init

接下来创建 Pnpm Workspace 的核心配置文件pnpm-workspace.yaml：

packages: - 'apps/*' - 'packages/*' - 'libs/*'

这个配置告诉 Pnpm 哪些目录下的包属于这个 Workspace。我们通常将应用放在apps/，共享组件放在packages/，工具库放在libs/。

2.3 初始化 Git 仓库

git init echo "node_modules" > .gitignore echo ".DS_Store" >> .gitignore

3. 配置基础项目结构

3.1 创建第一个 Vue 3 应用

在apps/目录下创建我们的第一个 Vue 3 应用：

pnpm create vite@latest 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.json

3.2 配置共享依赖

为了让所有子项目共享相同的 Vue 和 Vite 版本，我们在根目录安装这些依赖：

pnpm add vue@latest vite@latest -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.ts：

import { 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.vue：

<template> <button class="shared-button"> <slot></slot> </button> </template> <script setup lang="ts"> defineProps({ type: { type: String, default: 'default' } }) </script> <style scoped> .shared-button { padding: 8px 16px; border-radius: 4px; cursor: pointer; } </style>

创建入口文件packages/shared/src/index.ts：

import { 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.ts：

import { 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 install

6.2 使用共享组件

修改apps/my-app/src/App.vue：

<script setup lang="ts"> import { Button } from '@my/shared' </script> <template> <Button>来自共享组件的按钮</Button> </template>

6.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 优化构建输出

对于共享组件库，我们可以通过以下方式优化构建：

1. 按需加载：配置 Vite 输出多种格式（ESM、CJS）
2. 样式提取：将 CSS 提取到单独文件
3. 类型声明：生成完整的 TypeScript 类型定义

修改packages/shared/vite.config.ts：

export default defineConfig({ // ...其他配置 build: { lib: { // ...原有配置 formats: ['es', 'cjs'] }, cssCodeSplit: true, rollupOptions: { // ...原有配置 output: { assetFileNames: 'assets/[name][extname]', entryFileNames: '[format]/[name].js' } } } })

8. 常见问题解决

在实际开发中，你可能会遇到以下问题：

1. 依赖提升问题：Pnpm 默认不会提升依赖，可能导致某些包找不到 peerDependencies。解决方案是在.npmrc中添加：

   public-hoist-pattern[]=*vue* public-hoist-pattern[]=*vite*

2. HMR 不工作：确保 Vite 配置中正确设置了服务器选项：

   server: { watch: { usePolling: true, interval: 100 } }

3. 类型找不到：在共享包的package.json中确保正确设置了 types 路径：

   { "types": "dist/index.d.ts" }

4. 样式隔离：使用 CSS Modules 或 Scoped CSS 避免样式污染：

   <style module> /* 模块化样式 */ </style>

这套架构已经在多个生产环境中验证过稳定性，特别适合中大型 Vue 3 项目。随着项目规模扩大，你还可以考虑引入 Turborepo 优化构建流水线，或者 Vitest 作为统一的测试框架。