Vite 经典配置与前端集成

Vite 的价值不只是在命令行里跑一个 vite dev。项目一旦开始往真实协作场景走，最常碰到的还是这些事：别名怎么配、代理怎么走、环境变量怎么管、React 和 Vue 怎么接、打包产物怎么调、单仓库下怎么组织。

这一篇就按真实项目会碰到的顺序来收。

一个最常见的起步配置

import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'node:path'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')

  return {
    plugins: [react()],
    resolve: {
      alias: {
        '@': path.resolve(__dirname, './src'),
      },
    },
    server: {
      host: '0.0.0.0',
      port: 5173,
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL,
          changeOrigin: true,
        },
      },
    },
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@use "@/styles/variables.scss" as *;`,
        },
      },
    },
    build: {
      sourcemap: mode !== 'production',
      outDir: 'dist',
      assetsDir: 'assets',
    },
  }
})

这一份配置里已经覆盖了多数项目开局最常见的 5 件事：

• 插件接入
• 路径别名
• 代理
• 样式预处理器
• 构建输出

React 项目怎么接

React 项目最常见的是 @vitejs/plugin-react。

import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
})

这层通常会处理：

• JSX / TSX
• Fast Refresh
• React 相关编译能力

如果项目用了 svgr、mdx 或一些自定义 Babel 插件，也会在这层附近接进去。

Vue 项目怎么接

Vue 项目通常接 @vitejs/plugin-vue。

import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
})

如果还用了 JSX，可以再补 @vitejs/plugin-vue-jsx。

别名配置

前端项目里最常见的是把 src 提成 @。

resolve: {
  alias: {
    '@': path.resolve(__dirname, './src'),
  },
}

这件事看起来小，但一旦项目大起来，路径结构如果一直是 ../../../../，维护体验会明显变差。

开发代理

接口联调时，代理几乎是必配项。

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:3000',
      changeOrigin: true,
    },
  },
}

常见用途：

• 避免本地开发时的跨域问题
• 本地切换不同环境的后端地址
• BFF、网关或 mock 服务联调

环境变量

Vite 里最常见的读取方式是：

const baseUrl = import.meta.env.VITE_API_BASE_URL

要记住的边界

• 只有 VITE_ 前缀的变量会暴露到前端
• 不该给浏览器的内容，不要放进这层
• 真正的服务端密钥，不该依赖前端环境变量来保护

一个常见用法

const isProd = import.meta.env.PROD
const isDev = import.meta.env.DEV
const mode = import.meta.env.MODE

样式和静态资源

SCSS 全局变量注入

css: {
  preprocessorOptions: {
    scss: {
      additionalData: `@use "@/styles/variables.scss" as *;`,
    },
  },
}

资源引用

Vite 对图片、字体、SVG 这类静态资源的处理已经比较自然。多数情况下直接走模块导入即可。

import logoUrl from '@/assets/logo.svg'

构建输出怎么调

build: {
  outDir: 'dist',
  assetsDir: 'assets',
  sourcemap: true,
  rollupOptions: {
    output: {
      manualChunks: {
        react: ['react', 'react-dom'],
      },
    },
  },
}

常见关注点

• outDir：产物目录
• assetsDir：静态资源目录
• sourcemap：线上排错是否保留 source map
• manualChunks：大项目拆包策略

一个更进阶的配置参考

下面这份更接近中型项目常见的配置组合：

import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'
import svgr from 'vite-plugin-svgr'
import path from 'node:path'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')

  return {
    plugins: [react(), tsconfigPaths(), svgr()],
    resolve: {
      alias: {
        '@': path.resolve(__dirname, './src'),
        '@shared': path.resolve(__dirname, '../shared/src'),
      },
    },
    server: {
      host: '0.0.0.0',
      port: 5173,
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL,
          changeOrigin: true,
          rewrite: (p) => p.replace(/^\\/api/, ''),
        },
      },
    },
    css: {
      modules: {
        localsConvention: 'camelCaseOnly',
      },
      preprocessorOptions: {
        scss: {
          additionalData: `@use "@/styles/variables.scss" as *;`,
        },
      },
    },
    build: {
      target: 'es2022',
      sourcemap: mode !== 'production',
      outDir: 'dist',
      assetsDir: 'static',
      chunkSizeWarningLimit: 1200,
      rollupOptions: {
        output: {
          manualChunks: {
            react: ['react', 'react-dom'],
            vendor: ['axios', '@tanstack/react-query'],
          },
        },
      },
    },
    define: {
      __APP_VERSION__: JSON.stringify(process.env.npm_package_version),
    },
  }
})

这类配置里，比较常见的目标是：

• tsconfig paths 和运行时解析保持一致
• SVG 直接按组件导入
• 开发代理支持网关或 BFF 联调
• 样式模块和全局变量一起收住
• 拆包策略不要全靠默认值

前端项目里最常见的几类插件

1. 路径自动同步

例如 vite-tsconfig-paths，让 TypeScript 的 paths 和 Vite 解析保持一致。

2. SVG 组件化

例如 React 项目常接 vite-plugin-svgr。

3. Mock

本地开发时，有些团队会用 mock 插件把前后端联调拆开。

4. 检查和分析

打包分析、类型提示增强、Lint 集成，这些都可能放在插件链附近。

Monorepo 里怎么接

如果项目是 workspace 结构，Vite 里通常要多看两件事：

• 依赖包的解析路径
• 本地包的热更新和构建输出

多数情况下，Vite 在 monorepo 里并不难用，但一旦涉及共享 UI 包、工具包、Node 侧脚本和 Web 应用混跑，就需要早点把边界理清。

库模式

如果不是做应用，而是做组件库或工具库，Vite 也能直接切到 library mode。

build: {
  lib: {
    entry: 'src/index.ts',
    name: 'MyLib',
    fileName: 'my-lib',
  },
}

这种场景下更值得一起看 Rollup，因为很多产物输出思路和它是连着的。

一个更稳的判断

Vite 经典配置本身并不算重，难点大多出在项目边界：

• 这是应用还是库
• 这是单仓库还是 monorepo
• 这是只跑前端，还是还要接 SSR / Node
• 这是开发代理问题，还是环境变量设计问题

把这些前提先想清楚，Vite 配起来通常会很顺。