Vite 与 Webpack 在 React 项目中的配置差异

底层机制差异：为什么配置结构大相径庭

在很多初次从 Webpack 接触 Vite 的开发者眼中，最直观的震撼往往是配置文件的体积：原本在 Webpack 中需要长达数百行配置的 webpack.config.js，换到 Vite 中往往十几行 vite.config.js 就能直接启动 React 项目。这种代码量上的巨大落差，背后其实是构建范式与模块流转路径的彻底重构。

在 Webpack 的世界中，理念是“一切皆模块”。但是 Webpack 原生仅能理解 JavaScript 与 JSON 文件。为了构建出 React 应用，Webpack 必须从 JS 入口出发，递归遍历所有依赖；遇到 JSX 时调用 babel-loader，遇到样式时调用 css-loader，遇到图片时调用资产规则。在本地开发服务器（webpack-dev-server）启动之前，它必须把整个项目的依赖拓扑图在内存中完整构建并打包成最终的 bundle。因此，Webpack 的配置核心是“命令式管道”——开发者必须精确告诉打包器每一个正则匹配到的文件应该走哪些 Loader、各 Loader 之间如何顺序传递数据。

而 Vite 则选择逆向思考，将模块解析的繁重工作交还给现代浏览器原生的 ES Module 规范。在开发阶段，Vite 本地开发服务器本质上是一个轻量级的静态资源与中间件服务器。浏览器向服务器请求 /src/App.jsx 时，Vite 拦截这一 HTTP 请求，借助底层的 Go 语言高性能编译器 esbuild，仅对当前单个文件进行即时语法转换并输出标准 ESM 代码。因此，Vite 不需要提前为所有文件编排转译流水线，其配置转变为“声明式中间件”——只需声明需要激活哪些插件（如 React 插件），其余大量通用的样式、静态资源处理均已被 Vite 内置。

图 1：本地开发环境下的模块流转与配置介入点对比

入口管理与 HTML 处理机制

在 React 项目中，入口文件的定义是两者呈现给开发者的第一个分水岭。这个差异不仅改变了项目文件的物理存放位置，更重塑了 HTML 页面与业务 JavaScript 之间的从属关系。

在 Webpack 中，配置文件以 JavaScript 文件为起点。开发者在配置中显式指定 entry: './src/index.jsx'。此时 HTML 文件（通常位于 public/index.html）只是一个被动的宿主模板。为了把构建出来的脚本标签注入到 HTML 中，必须引入并实例化 HtmlWebpackPlugin：

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  mode: 'development',
  // 入口明确指向 JS/JSX 文件
  entry: './src/index.jsx',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash:8].js',
    clean: true,
  },
  plugins: [
    // 必须通过插件将打包后的 JS 注入模板 HTML
    new HtmlWebpackPlugin({
      template: path.resolve(__dirname, 'public/index.html'),
      inject: 'body',
    }),
  ],
};

反观 Vite，入口则是项目根目录下的 index.html。HTML 文件直接作为项目源码的一部分，而不是构建模板。在 index.html 中，开发者显式书写浏览器标准模块引入：

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <title>React App</title>
  </head>
  <body>
    <div id="root"></div>
    <!-- 原生模块入口：Vite 自动拦截该路径并编译对应文件 -->
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

正因为 index.html 扮演了入口，Vite 的 vite.config.js 中甚至无需配置任何入口字段，默认即可运行。在多页面应用（MPA）场景下，Vite 也只需要在 build.rollupOptions.input 中列出多个 HTML 文件路径，心智模型与原生 Web 规范完全对齐。

React 与 JSX 转译：多层 Loader 栈对标单一插件

React 项目的核心诉求在于将 JSX 语法转换为浏览器可识别的标准 JavaScript，并兼顾开发阶段组件状态保全的模块热替换（Fast Refresh）。在这点上，两者的配置复杂度形成了极鲜明的反差。

在 Webpack 中，要实现现代 React 17/18 的 JSX 自动运行时（即无需手动 import React from 'react'）与热更新，需要手动组合安装 @babel/core、babel-loader、@babel/preset-react，并在开发环境下引入 react-refresh 和 @pmmmwh/react-refresh-webpack-plugin：

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|jsx)$/,
        exclude: /node_modules/,
        use: [
          {
            loader: require.resolve('babel-loader'),
            options: {
              presets: [
                '@babel/preset-env',
                ['@babel/preset-react', { runtime: 'automatic' }] // 新 JSX 运行时
              ],
              plugins: [
                isDevelopment && require.resolve('react-refresh/babel')
              ].filter(Boolean),
            },
          },
        ],
      },
    ],
  },
  plugins: [
    isDevelopment && new ReactRefreshWebpackPlugin(),
  ].filter(Boolean),
};

而在 Vite 中，上述一整套 Loader 与 Babel 插件被高度封装到了官方插件 @vitejs/plugin-react（基于 Babel 和 Fast Refresh）或 @vitejs/plugin-react-swc（基于 Rust 实现的极速编译器 SWC）中。开发者在 vite.config.js 中只需引入并声明该插件，JSX 语法转译、新版 JSX 运行时注入、以及 Fast Refresh 热更新支持便全部就绪：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  // 单一插件囊括 JSX 运行时与 Fast Refresh
  plugins: [react()],
});

图 2：React 项目关键工程化维度的配置映射全景

样式处理与 CSS Modules：流水线编排对标开箱即用

在 React 生态中，模块化样式（CSS Modules）与 Sass/Less 预处理器几乎是大型项目的标配。两者在此处的配置分歧再次印证了“规则编排”与“约定优于配置”的区别。

在 Webpack 中，样式的处理顺序严格受限于 Loader 从右向左（由底向上）的管道机制。以 Sass + CSS Modules 为例，开发环境需要 style-loader 把样式插入 DOM，生产环境则要替换为 MiniCssExtractPlugin.loader 提取独立 CSS 文件；中间还需要经过 css-loader 解析类名映射，以及 postcss-loader 补全浏览器前缀。开发者经常会因为 loader 顺序写反而遭遇无法解释的构建报错：

const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const isProd = process.env.NODE_ENV === 'production';

module.exports = {
  module: {
    rules: [
      {
        test: /\.module\.(css|scss)$/,
        use: [
          isProd ? MiniCssExtractPlugin.loader : 'style-loader',
          {
            loader: 'css-loader',
            options: {
              modules: {
                localIdentName: '[name]__[local]--[hash:base64:5]',
              },
            },
          },
          'postcss-loader',
          'sass-loader',
        ],
      },
    ],
  },
};

而 Vite 内置了针对 CSS、PostCSS 与 CSS Modules 的全套处理逻辑。只要业务组件中引入的文件名符合 [name].module.css 或 [name].module.scss 约定，Vite 会自动开启作用域隔离并导出类名映射对象。对于 Sass/Less，开发者完全不需要在 vite.config.js 中配置规则，仅需在项目中执行 npm install -D sass 安装预处理器本身，Vite 便能自动探测并按需调用编译。只有在需要统一注入全局变量或修改类名生成格式时，才需要编写配置：

import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    // 可选：微调 CSS Modules 命名规则
    modules: {
      generateScopedName: '[name]__[local]___[hash:base64:5]',
    },
    // 可选：为预处理器注入全局变量，无需配置 loader 链
    preprocessorOptions: {
      scss: {
        additionalData: '@import "@/styles/variables.scss";',
      },
    },
  },
});

静态资产、路径别名与环境变量

在实际项目业务代码中，资源寻址与环境参数是与开发者接触最频繁的配置领域。两者的差异直接决定了代码中的书写习惯。

1. 静态资源加载

Webpack 5 废弃了早期的 file-loader 和 url-loader，统一归口为 Asset Modules。开发者依然需要在 module.rules 中配置资源类型规则（例如 type: 'asset' 配合大小阈值来自动决定内联 Base64 还是生成独立文件）。而在 Vite 中，导入静态资产（图片、音视频、字体）会默认返回解析后的公共 URL；更进一步，Vite 提供了极其灵活的导入后缀修饰符：

• import imgUrl from './logo.png'：返回资源部署后的静态 URL。
• import svgRaw from './icon.svg?raw'：直接以纯文本字符串格式导入 SVG 源码（常用于 React 内联动态图标）。
• import worker from './worker.js?worker'：直接实例化 Web Worker。

2. 路径别名（Resolve Alias）

在路径别名的支持上，两者的配置键名类似，均位于 resolve.alias。但需要注意的是，Webpack 通常会配置广泛的 resolve.extensions: ['.js', '.jsx', '.json'] 来允许在代码中省略文件后缀；而 Vite 强烈不推荐在 React 中省略 .jsx 后缀，因为在开发阶段浏览器需要明确的 MIME 类型与静态路径来建立依赖关系。

// Webpack: 常用对象映射，习惯性忽略后缀
resolve: {
  alias: {
    '@': path.resolve(__dirname, 'src'),
  },
  extensions: ['.js', '.jsx', '.json'],
}

// Vite: 同样使用 resolve.alias，但推荐规范书写文件后缀
resolve: {
  alias: {
    '@': path.resolve(__dirname, './src'),
  },
}

3. 环境变量注入机制

Webpack 默认依托 Node.js 环境，通常利用 webpack.DefinePlugin 配合 dotenv 库把外部变量写入到代码中的 process.env。在 Create React App 等脚手架中，变量约定以 REACT_APP_ 前缀命名。

Vite 则拥抱现代标准，将客户端环境变量挂载在 import.meta.env 对象上，且默认强制要求以 VITE_ 为前缀命名以防系统敏感密钥泄漏。如果在 vite.config.js 配置文件自身需要根据开发/生产模式读取环境变量，不能直接访问 process.env，而必须使用 Vite 导出的 loadEnv 工具函数：

import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  // 显式加载当前环境对应的 .env 文件
  const env = loadEnv(mode, process.cwd(), '');
  
  return {
    server: {
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL, // 读取环境变量
          changeOrigin: true,
        },
      },
    },
  };
});

生产构建与代码分割：SplitChunks 对标 Rollup ManualChunks

如果说本地开发体验是 Vite 的主场，那么生产环境打包（Build）则是两者真正展开深度博弈的战场。Webpack 在生产构建中沿用自身的依赖图模型，通过极度细致的 optimization.splitChunks 掌控每一个字节的去向；而 Vite 在生产环境下则交棒给成熟的 Rollup。

在 Webpack 中，为了将 React 核心库、第三方图表库与业务代码剥离为独立 chunk，配置通常如下展开：

optimization: {
  splitChunks: {
    chunks: 'all',
    cacheGroups: {
      reactVendor: {
        test: /[\/]node_modules[\/](react|react-dom|react-router-dom)[\/]/,
        name: 'vendor-react',
        priority: 20,
        reuseExistingChunk: true,
      },
      commonVendor: {
        test: /[\/]node_modules[\/]/,
        name: 'vendor-common',
        priority: 10,
        minChunks: 2,
      },
    },
  },
}

而在 Vite 中，生产优化的配置直接收敛在 build.rollupOptions 下。Rollup 原生出色的 Tree-shaking 能够输出极为干净的产物。分包规则可以通过 manualChunks 函数或对象进行直观指定：

build: {
  target: 'es2015',
  outDir: 'dist',
  rollupOptions: {
    output: {
      // 手动将核心依赖划分为独立 chunk 提升浏览器缓存命中率
      manualChunks: {
        'react-vendor': ['react', 'react-dom', 'react-router-dom'],
      },
    },
  },
}

图 3：从 Webpack 向 Vite 迁移配置的实操执行流程

实战迁移步骤与避坑指南

将一个现有的 Webpack React 项目迁移至 Vite，绝非简单替换一个配置文件即可万事大吉。由于两者的运行时假设不同，以下几个典型细节如果不加注意，极易导致项目启动白屏或构建中断：

1. JSX 扩展名严格限制： Webpack 允许在 .js 文件中随意编写 JSX，因为 babel-loader 会无差别扫描；但 Vite 底层用于快速转译的 esbuild 默认禁止在 .js 文件中解析 JSX 语法。如果项目中存在包含 JSX 的 .js 文件，必须批量重命名为 .jsx，或在 vite.config.js 中配置 esbuild: { loader: { '.js': 'jsx' } }（推荐前者以符合规范）。
2. Node.js 全局对象与 Polyfill 缺失： Webpack 5 虽移除了大部分 Node polyfill，但旧项目常用插件依然会自动注入或容易补齐 global、Buffer 或 process。Vite 运行在纯净的浏览器沙箱环境，遇到遗留老库直接调用 global.xxx 时会抛出未定义异常。可在配置中通过 define: { 'global': 'window' } 进行垫片补齐。
3. CommonJS 模块与预构建陷阱： 某些历史悠久的 React 第三方包可能仅发布了 CommonJS 格式产物。虽然 Vite 会通过 esbuild 对 node_modules 进行预构建（Pre-bundling）转为 ESM，但遇到动态 require 等复杂代码时偶有失效。此时需要在 optimizeDeps.include 中显式声明该包名称强制预打包。

选型决策与完整配置对照清单

在实际企业级工程实践中，构建工具的选型从来不是非黑即白的站队，而是根据团队交付痛点与资产包袱做出的理性权衡。

图 4：React 项目构建工具选型与配置决策树

为了给日常开发与项目重构提供立竿见影的参考，以下分别给出一套工业级可运行的 webpack.config.js 与对标的 vite.config.js 完整代码。

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const ReactRefreshPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

const isDev = process.env.NODE_ENV !== 'production';

module.exports = {
  mode: isDev ? 'development' : 'production',
  entry: './src/index.jsx',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash:8].js',
    clean: true,
  },
  resolve: {
    alias: { '@': path.resolve(__dirname, 'src') },
    extensions: ['.js', '.jsx'],
  },
  module: {
    rules: [
      {
        test: /\.(js|jsx)$/,
        exclude: /node_modules/,
        use: [{
          loader: 'babel-loader',
          options: {
            presets: [
              '@babel/preset-env',
              ['@babel/preset-react', { runtime: 'automatic' }]
            ],
            plugins: [isDev && 'react-refresh/babel'].filter(Boolean),
          },
        }],
      },
      {
        test: /\.module\.css$/,
        use: [
          isDev ? 'style-loader' : MiniCssExtractPlugin.loader,
          {
            loader: 'css-loader',
            options: { modules: true },
          },
        ],
      },
      {
        test: /\.(png|svg|jpg|jpeg|gif)$/i,
        type: 'asset/resource',
      },
    ],
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './public/index.html',
    }),
    isDev && new ReactRefreshPlugin(),
    !isDev && new MiniCssExtractPlugin({
      filename: '[name].[contenthash:8].css',
    }),
  ].filter(Boolean),
  devServer: {
    port: 3000,
    hot: true,
    historyApiFallback: true,
  },
};

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  // 核心插件：覆盖 JSX、Fast Refresh 与自动运行时
  plugins: [react()],

  // 路径别名定义
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },

  // 本地开发服务器
  server: {
    port: 3000,
    open: true,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },

  // 生产构建配置（底层直接委托 Rollup）
  build: {
    target: 'es2015',
    outDir: 'dist',
    rollupOptions: {
      output: {
        manualChunks: {
          'react-core': ['react', 'react-dom'],
        },
      },
    },
  },
});

对比上述两套配置可以清晰发现，Vite 并非在 Webpack 的基础上做了语法糖封装，而是通过技术栈的代际升级，将以往开发者必须在构建端手动处理的繁重逻辑，分解交由浏览器原生能力（ESM）、编译工具（esbuild）与专业打包器（Rollup）各自承担。对于绝大多数中新建 React 现代项目而言，选择 Vite 能够极大降低工程化维护成本，带来近乎瞬时的本地调试体验；而在面对具有深度微前端定制需求、依赖复杂历史资产管道的超大型企业级单体应用时，Webpack 依然凭借无死角的灵活性发挥着不可替代的中流砥柱作用。