Vue2+Vite+TypeScript企业级项目现代化改造实践

1. 为什么选择Vue2+Vite+TypeScript技术栈

十年前我刚接触前端时，Webpack还是新鲜事物，如今Vite已经彻底改变了前端开发体验。最近在重构一个遗留的Vue2企业级项目时，我决定采用Vite+TypeScript进行现代化改造。这个组合看似矛盾——Vue2作为"过时"框架，Vite作为新兴构建工具，TypeScript作为强类型语言，但实际配合起来却异常默契。

Vite的闪电般冷启动速度（实测项目启动从原来的47秒降到1.3秒）和热更新能力，让老项目获得了新生。而TypeScript的加入，则让这个原本充满any类型的老项目获得了完善的类型检查。在VS Code中，现在能准确识别出组件props类型，代码跳转准确率提升80%以上。

2. 项目初始化与基础配置

2.1 创建项目骨架

首先通过命令行初始化项目：

bash复制npm create vite@latest legacy-project --template vue-ts

这里有个关键技巧：虽然使用了vue-ts模板，但我们需要手动调整支持Vue2。修改vite.config.ts：

typescript复制import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue2'
import path from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

注意必须安装专为Vue2适配的插件：

bash复制npm install @vitejs/plugin-vue2 -D

2.2 TypeScript配置要点

tsconfig.json需要特别调整兼容Vue2：

json复制{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "strict": true,
    "jsx": "preserve",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
  "exclude": ["node_modules"]
}

关键点在于：

1. 必须包含.vue文件类型声明
2. 设置skipLibCheck避免第三方库类型检查问题
3. 配置paths支持别名

3. 大型项目分包策略实现

3.1 路由级代码分割

在Vite中实现路由懒加载比Webpack更简洁：

typescript复制const routes = [
  {
    path: '/dashboard',
    component: () => import('@/views/Dashboard.vue'),
    meta: { requiresAuth: true }
  }
]

Vite会自动将这些import转换为动态导入，生成独立的chunk文件。但要注意：

避免在同一个文件中混合使用静态和动态导入，这会导致Vite的预打包策略失效

3.2 组件库按需加载

对于Element UI这类大型组件库，推荐使用unplugin-vue-components实现自动按需导入：

typescript复制// vite.config.ts
import Components from 'unplugin-vue-components/vite'
import { ElementUiResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  plugins: [
    Components({
      resolvers: [ElementUiResolver()]
    })
  ]
})

实测这种方式比传统babel-plugin-import方式打包体积减少约30%。

3.3 第三方依赖分包

通过manualChunks优化vendor：

typescript复制export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          echarts: ['echarts'],
          axios: ['axios'],
          vue: ['vue', 'vue-router', 'vuex']
        }
      }
    }
  }
})

建议将变化频率不同的库分开：

• 高频变更：业务组件
• 中频变更：工具类库
• 低频变更：框架类库

4. 类型系统深度集成

4.1 Vue组件的TypeScript支持

为Vue2组件添加类型需要一些技巧：

typescript复制import { Component, Vue } from 'vue-property-decorator'

@Component
export default class MyComponent extends Vue {
  // 声明props类型
  @Prop({ type: String, required: true }) readonly title!: string
  
  // 计算属性
  get reversedTitle(): string {
    return this.title.split('').reverse().join('')
  }
  
  // 方法
  handleClick(event: MouseEvent): void {
    this.$emit('click', event)
  }
}

对于不想用装饰器的项目，可以使用vue-facing-decorator：

typescript复制import { defineComponent } from 'vue'

export default defineComponent({
  props: {
    message: {
      type: String,
      required: true
    }
  },
  setup(props) {
    const count = ref(0)
    return { count }
  }
})

4.2 Vuex的类型增强

创建增强后的store类型：

typescript复制// store/types.ts
import { ComponentCustomProperties } from 'vue'
import { Store } from 'vuex'

declare module '@vue/runtime-core' {
  interface State {
    count: number
  }

  interface ComponentCustomProperties {
    $store: Store<State>
  }
}

然后在store定义中使用：

typescript复制import { InjectionKey } from 'vue'
import { createStore, Store } from 'vuex'

export const key: InjectionKey<Store<State>> = Symbol()

export const store = createStore<State>({
  state: {
    count: 0
  },
  mutations: {
    increment(state) {
      state.count++
    }
  }
})

5. 性能优化实战技巧

5.1 编译时优化

启用Vite的构建优化：

typescript复制export default defineConfig({
  build: {
    target: 'es2015',
    minify: 'terser',
    terserOptions: {
      compress: {
        drop_console: process.env.NODE_ENV === 'production'
      }
    }
  }
})

5.2 运行时优化

使用vue-virtual-scroller优化长列表：

typescript复制import { RecycleScroller } from 'vue-virtual-scroller'

export default {
  components: { RecycleScroller },
  data() {
    return {
      items: [] // 大数据量数组
    }
  }
}

模板中使用：

html复制<RecycleScroller
  class="scroller"
  :items="items"
  :item-size="54"
  key-field="id"
>
  <template v-slot="{ item }">
    <!-- 渲染单个项 -->
  </template>
</RecycleScroller>

5.3 预加载策略

配置preload插件自动生成preload标签：

typescript复制import { createHtmlPlugin } from 'vite-plugin-html'

export default defineConfig({
  plugins: [
    createHtmlPlugin({
      minify: true,
      entry: '/src/main.ts',
      template: 'index.html',
      inject: {
        data: {
          title: 'My App'
        }
      }
    })
  ]
})

6. 调试与错误处理

6.1 类型错误排查

常见的Vue2+TS类型问题及解决方案：

1. $refs类型问题：

typescript复制(this.$refs.form as Vue & { validate: () => boolean }).validate()

2. 事件参数类型：

typescript复制@Emit('submit')
handleSubmit(payload: { id: number; name: string }) {
  return payload
}

3. 第三方库扩展：

typescript复制declare module 'vue/types/vue' {
  interface Vue {
    $myPlugin: MyPluginType
  }
}

6.2 生产环境问题追踪

配置Sentry监控：

typescript复制import * as Sentry from '@sentry/vue'
import { Integrations } from '@sentry/tracing'

Sentry.init({
  Vue,
  dsn: 'your_dsn',
  integrations: [new Integrations.BrowserTracing()],
  tracesSampleRate: 0.2
})

在Vite中正确生成sourcemap：

typescript复制export default defineConfig({
  build: {
    sourcemap: true
  }
})

7. 迁移与升级策略

7.1 渐进式迁移方案

对于大型老项目，推荐采用渐进式迁移：

1. 先在现有Webpack项目中引入Vite作为开发服务器
2. 逐步将模块改为ESM格式
3. 添加TypeScript支持
4. 最后完全迁移到Vite构建

可以在vite.config.ts中配置兼容旧路径：

typescript复制export default defineConfig({
  server: {
    proxy: {
      '/legacy': {
        target: 'http://localhost:8080',
        rewrite: path => path.replace(/^\/legacy/, '')
      }
    }
  }
})

7.2 性能对比数据

在我们的电商项目中，迁移前后对比：

8. 项目结构最佳实践

推荐的大型项目目录结构：

code复制src/
├── assets/          # 静态资源
├── components/      # 公共组件
│   ├── base/        # 基础UI组件
│   ├── business/    # 业务组件
│   └── index.ts     # 组件自动注册
├── composables/     # 组合式函数
├── directives/      # 自定义指令
├── router/          # 路由配置
│   ├── modules/     # 路由模块拆分
│   └── index.ts
├── store/           # Vuex状态管理
│   ├── modules/     # 模块化store
│   └── index.ts
├── styles/          # 全局样式
├── utils/           # 工具函数
├── views/           # 页面组件
├── App.vue          # 根组件
└── main.ts          # 入口文件

关键点：

• 按功能而非类型组织代码
• 每个模块应该有明确的职责边界
• 使用index.ts作为模块入口

9. 持续集成与部署

9.1 CI配置示例

GitHub Actions配置示例：

yaml复制name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v2
      with:
        node-version: '16'
    - run: npm ci
    - run: npm run build
    - uses: actions/upload-artifact@v2
      with:
        name: dist
        path: dist

9.2 自动化部署

使用Docker构建生产镜像：

dockerfile复制FROM nginx:alpine
COPY dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

优化后的nginx配置：

nginx复制server {
  listen 80;
  gzip on;
  gzip_types text/plain text/css application/json application/javascript text/xml;

  location / {
    root /usr/share/nginx/html;
    index index.html;
    try_files $uri $uri/ /index.html;
  }
}

10. 经验总结与避坑指南

在完成这个大型项目迁移后，我总结了以下关键经验：

1. 类型扩展要尽早：在项目初期就建立完善的类型定义，后期补充成本很高

2. 分包策略要实测：不同项目的代码分割策略需要根据实际路由和使用情况调整

3. 监控不能少：生产环境必须配置完善的错误监控系统

4. 渐进式迁移：大型项目不要试图一次性完成迁移，应该分阶段进行

5. 团队协作规范：TypeScript需要团队统一编码风格，建议使用ESLint+Prettier

特别提醒几个常见陷阱：

避免在Vue2中使用Composition API的ref直接赋值给data属性，这会导致响应性丢失

Vite的env变量需要以VITE_前缀开头才能被识别，不同于Webpack的VUE_APP_前缀

当使用动态导入时，确保路径是静态字符串，否则Vite无法正确分析依赖