1. 项目概述
最近接手了一个企业级中后台系统的前端架构工作，需要基于Vue2技术栈搭建一个可维护性强、开发体验好的项目基础。考虑到团队已经熟悉Vue2生态但又有TypeScript的使用需求，最终选择了Vite + Vue2 + TypeScript的技术组合，并使用pnpm workspace实现模块化分包架构。
这种架构方案主要解决了我们面临的几个痛点：
- 老项目代码臃肿难以维护
- 多人协作时代码冲突频繁
- 构建速度随着项目增长越来越慢
- 需要渐进式迁移到TypeScript
2. 环境准备与工具选型
2.1 开发环境要求
在开始项目搭建前，需要确保开发环境满足以下要求：
code复制node -v # 需≥16.0.0
pnpm -v # 需≥7.0.0
推荐使用nvm管理Node版本，可以方便切换不同项目所需的Node版本：
bash复制nvm install 18.18.2
nvm use 18.18.2
2.2 工具选型理由
为什么选择这些工具组合？
-
Vite：相比Webpack，Vite的启动速度和热更新速度有显著提升，特别是对于大型项目。实测在我们的代码量下，冷启动时间从45s缩短到1.5s。
-
pnpm：相比npm/yarn，pnpm的磁盘空间利用率更高（节省约40%空间），安装速度更快，且workspace功能完善，非常适合monorepo项目。
-
Vue2：由于历史原因，团队已有大量Vue2组件和业务代码，直接升级Vue3成本过高。
-
TypeScript：随着项目复杂度提升，JavaScript的动态类型系统已经无法满足我们的维护需求，TypeScript的静态类型检查可以显著提高代码质量。
3. 项目结构设计
3.1 目录结构规划
我们采用了三层分包结构：
code复制xx-business/
├── common/ # 公共模块
├── main/ # 主入口模块
└── pages/ # 业务模块
├── login/
└── home/
这种结构的优势在于：
- 公共代码集中管理，避免重复
- 业务模块物理隔离，降低耦合
- 各模块可以独立开发和构建
3.2 pnpm workspace配置
根目录下的pnpm-workspace.yaml定义了工作区范围：
yaml复制packages:
- 'common'
- 'main'
- 'pages/*'
这样配置后，我们可以：
- 在根目录执行
pnpm add -w安装全局依赖 - 使用
pnpm -F <package>为指定模块安装依赖 - 跨模块引用时自动处理依赖关系
4. 核心配置详解
4.1 TypeScript配置
全局tsconfig.json的关键配置项说明：
json复制{
"compilerOptions": {
"paths": {
"/common/*": ["common/*"],
"/main/*": ["main/*"],
"/pages/*": ["pages/*"]
}
}
}
这个路径映射配置使得我们可以直接通过绝对路径引用其他模块的代码，例如：
typescript复制import { utils } from '/common/utils'
4.2 Vite基础配置
vite.config.base.ts中需要特别注意Vue2的插件配置：
typescript复制import { createVuePlugin } from 'vite-plugin-vue2'
export default defineConfig({
plugins: [
createVuePlugin({
jsx: true // 启用JSX支持
})
]
})
4.3 ESLint配置
.eslintrc.js中我们做了这些特殊处理：
javascript复制rules: {
'vue/multi-word-component-names': 'off', // 允许单单词组件名
'@typescript-eslint/no-explicit-any': 'warn' // 不强制禁止any类型
}
这些规则放宽是为了兼容现有代码，新代码仍应遵循更严格的规范。
5. 模块开发实践
5.1 公共模块开发
common模块存放了以下内容：
- 工具函数库
- 全局样式
- 公共组件
- 类型定义
在common/src/utils.ts中：
typescript复制// 防抖函数实现
export function debounce<T extends (...args: any[]) => any>(
fn: T,
delay: number
): (...args: Parameters<T>) => void {
let timer: number | null = null
return function(...args: Parameters<T>) {
if (timer) clearTimeout(timer)
timer = setTimeout(() => fn(...args), delay)
}
}
5.2 业务模块开发
以登录模块为例，典型的页面结构：
code复制pages/login/
├── src/
│ ├── components/ # 模块私有组件
│ ├── views/ # 页面组件
│ ├── api.ts # API接口
│ ├── router.ts # 路由配置
│ └── store.ts # 状态管理
在模块的vite.config.ts中需要特别配置：
typescript复制export default mergeConfig(baseConfig, {
server: {
port: 3001 // 为每个模块指定不同端口
}
})
6. 开发与构建流程
6.1 开发模式运行
启动主入口模块开发服务器：
bash复制pnpm dev:main
启动指定业务模块开发服务器：
bash复制pnpm -F pages/login run dev
6.2 生产环境构建
构建所有模块：
bash复制pnpm build:all
构建指定模块：
bash复制pnpm -F main run build
7. 常见问题与解决方案
7.1 类型定义问题
问题：Vue2组件中使用TypeScript时，模板内的类型检查不生效。
解决方案：安装@vue/runtime-dom并配置：
typescript复制declare module '*.vue' {
import Vue from 'vue'
export default Vue
}
7.2 样式隔离问题
问题：模块间的样式污染。
解决方案：使用scoped样式或CSS Modules：
vue复制<style module>
/* 模块化样式 */
</style>
7.3 依赖共享问题
问题：多个模块依赖同一个库的不同版本。
解决方案：在根目录package.json中声明peerDependencies：
json复制"peerDependencies": {
"vue": "^2.6.14"
}
8. 性能优化实践
8.1 构建速度优化
通过以下配置显著提升构建速度：
typescript复制// vite.config.ts
export default defineConfig({
build: {
minify: 'terser',
terserOptions: {
compress: {
drop_console: true
}
}
}
})
8.2 运行时性能优化
实现组件懒加载：
typescript复制const Home = () => import('/pages/home/src/views/Home.vue')
9. 项目经验总结
在实际开发中，我们总结了以下几点经验：
-
类型定义先行：在开发新功能时，先定义好类型接口，可以大幅减少后续的调试时间。
-
模块边界清晰：严格规定模块间的通信方式，避免直接跨模块引用实现细节。
-
渐进式迁移：对于老项目迁移，可以先将配置切换到新架构，再逐步迁移模块。
-
统一代码风格：使用ESLint+Prettier确保团队代码风格一致，这在多人协作中尤为重要。
这个架构方案经过半年多的生产环境验证，在可维护性、开发体验和构建性能方面都达到了预期目标。特别是对于大型项目，分包架构的优势会随着项目规模的增长而愈发明显。