How to Migrate Vue2 Projects to Vite 2.3.7: Step-by-Step Guide & Common Pitfalls

Current version

[email protected]

1. Suitable projects for migration

Systems using Vue2.

Internal systems without large traffic, where frequent base changes cause instability.

Non‑SSR systems (SSR still has many issues).

Projects with regular maintenance.

Projects with pain points such as slow bundling, cold start, or HMR.

Note: Vite uses Rollup for production; the migration cost may be high, so use with caution.

2. Migration steps

Use an internal system as a case study: develop with Vite, keep Webpack for production.

Understand Vite features; consult the official docs for updates.

Install required packages:

npm i [email protected] [email protected] [email protected] -D

Add a script in package.json: "vite": "NODE_ENV=development vite" Create and configure vite.config.js (default filename can be changed).

Sample vite.config.js

import { defineConfig } from 'vite';
import path from 'path';
import fs from 'fs';
import { createVuePlugin } from 'vite-plugin-vue2';
import { injectHtml, minifyHtml } from 'vite-plugin-html';
import { cjs2esmVitePlugin } from 'cjs2esmodule';
import dotenv from 'dotenv';

const config = require('./config');

try {
  const file = dotenv.parse(
    fs.readFileSync(`./config/.env.${process.env.NODE_ENV}`),
    { debug: true }
  );
  console.log(file);
  for (const key in file) {
    process.env[key] = file[key];
  }
} catch (e) {
  console.error(e);
}
const API_LOCATION = process.env.API_LOCATION || '/api';

function resolve(dir) {
  return path.join(__dirname, './', dir);
}

export default defineConfig({
  root: './',
  publicDir: 'public',
  base: './',
  mode: 'development',
  optimizeDeps: { include: [] },
  resolve: {
    alias: {
      vendor: resolve('src/vendor'),
      '@': resolve('src'),
      '~@': resolve('src'),
      '~component': resolve('src/components'),
      '~config': resolve('config')
    }
  },
  plugins: [
    cjs2esmVitePlugin(),
    createVuePlugin({ jsx: true, jsxOptions: { injectH: false } }),
    minifyHtml(),
    injectHtml({
      injectData: {
        htmlWebpackPlugin: { options: { isVite: true, shotcut: '/static/img/favicon.png' } },
        title: 'HMO 运营后台'
      }
    })
  ],
  define: { 'process.env': process.env },
  server: {
    host: 'liang.myweb.com',
    open: true,
    port: process.env.PORT || config.dev.port,
    proxy: {
      [API_LOCATION]: {
        target: 'http://127.0.0.1:8001',
        rewrite: path => path.replace(API_LOCATION, '')
      }
    }
  }
});

3. Common issues (Pitfalls)

1. Entry file must be index.html at project root.

Solution: adjust vite.config.js to inject the correct template.

import { injectHtml } from 'vite-plugin-html';
export default defineConfig({
  plugins: [
    injectHtml({
      injectData: {
        htmlWebpackPlugin: { options: { isVite: true, shotcut: '/static/img/favicon.png' } },
        title: 'HMO 运营后台'
      }
    })
  ]
});

2. Version‑specific errors – downgrade to an older Vite version if needed.

3. Missing named export error.

Uncaught SyntaxError: The requested module '/config/index.js' does not provide an export named 'default'

4. Proxy configuration – use http-proxy options.

proxy: {
  '/rest': {
    target: 'http://my.web.com/',
    changeOrigin: true,
    bypass: (req, res, proxyOption) => {
      console.log(`Current proxy request: ${req.url} -> ${proxyOption.target}`);
    }
  }
}

5. TypeScript errors – ensure Vite’s TS handling is configured.

"compilerOptions": {
  "types": ["vite/client"]
}

6. Global environment variable errors.

Use import.meta.env or define 'process.env' in the define section.

7. Debugging – run Vite with --debug or add console logs in the config.

8. File extensions – Vue files must include the .vue extension.

error: No loader is configured for ".vue"

9. Less files not found.

Install Less and add alias for ~@ to resolve the path.

10. JSX support – enable in vite.config.js via createVuePlugin({ jsx: true }) .

11. Proxy based on environment variables – use cross-env and dotenv to load .env files and configure server.proxy accordingly.

12. Process variable errors – Vite does not provide process by default; replace with import.meta.env or define a stub.

13. Other miscellaneous issues – many edge cases appear after adopting Vite; continue tracking them.