Integrating Vite into Vue 2.x Projects: Compatibility, Configuration, and Migration Guide

The article introduces the motivation for using Vite in a Vue 2.x H5 project, highlighting that bundless tools like Vite can dramatically reduce initial startup time compared to traditional Vue‑CLI builds.

Key compatibility challenges and solutions :

Vite does not expose the process variable; the guide shows how to define it globally via define: { 'process.env': process.env } or a custom polyfill.

Global global can be added in index.html or via vite-plugin-global-polyfill .

Vue‑CLI style deep selector /deep/ must be replaced with ::v-deep .

All single‑file components must include the .vue extension.

Path aliases using ~@ require explicit resolve.alias configuration.

Node‑sass and dart‑sass conflicts are resolved by forcing sass-loader to use node-sass in vue.config.js .

For the internal @jd/pandora-mobile component library, set an alias to the CommonJS build or adjust resolve.mainFields to prioritize compatible entry points.

Required Vite dependencies :

vite
vite-plugin-vue2
@vitejs/plugin-legacy
vite-plugin-html
vite-plugin-style-import
vite-plugin-env-switch
vite-plugin-global-polyfill
@rollup/plugin-babel
sass
@vitejs/plugin-legacy

Template file adjustments :

<script type="module" src="/src/main.js"></script>

Because Vite builds in the project root, an index.html file is added to coexist with the existing Vue‑CLI build output.

Vite configuration (vite.config.ts) :

import { defineConfig } from 'vite'
import legacy from '@vitejs/plugin-legacy'
import { createVuePlugin } from 'vite-plugin-vue2'
import createStyleImportPlugin from 'vite-plugin-style-import'
import envSwitchPlugin from 'vite-plugin-env-switch'
import globalPolyfill from 'vite-plugin-global-polyfill'
import { resolve } from 'path'

export default defineConfig({
  base: '/express-vite/',
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
      '~@': resolve(__dirname, 'src'),
      // '@jd/pandora-mobile': resolve(__dirname, 'node_modules/@jd/pandora-mobile/dist/pandora-mobile.js')
    },
    mainFields: ['main', 'module', 'jsnext:main', 'jsnext']
  },
  plugins: [
    envSwitchPlugin({
      wsProtocol: 'vite-hmr',
      envs: ['prepare', 'development', 'production'],
      wsPath: 'wss://xxx.jd.com/express-vite/',
      root: __dirname,
      eventName: 'env-check'
    }),
    globalPolyfill(),
    createStyleImportPlugin({
      libs: [{
        libraryName: '@jd/pandora-mobile',
        esModule: true,
        resolveStyle: name => `@jd/pandora-mobile/es/components/${name}/style/index.css`
      }]
    }),
    createVuePlugin(),
    legacy({ targets: ['defaults', 'not IE 11'] })
  ],
  define: { 'process.env': process.env },
  server: { host: 'xxx.jd.com', https: true, port: 443, open: true }
})

Performance comparison shows that Vite starts the H5 project in roughly one minute, while Vue‑CLI takes longer; however, Vite’s runtime bundling can cause noticeable UI lag on first interaction, and some SDK compatibility issues remain.

The article concludes with a summary of the migration steps, highlights remaining challenges (e.g., circular constant imports, SDK compatibility), and provides references for further reading.