施工蓝图：vite.config.js —— 项目的指挥中心

一句话本质 ：vite.config.js 是 Vite 项目的配置入口，通过 defineConfig 导出一个配置对象，统筹插件系统、路径别名、打包配置三大核心，决定整个项目的开发与构建流程。

核心要点：

插件（plugins） 像工地上的不同工种，各管一摊：React 启动、JSX 转换、CSS-in-JS 优化、热更新等。

路径别名（resolve.alias） 用 @、~、# 等符号给深层目录"取近道"，缩短导入路径、提升可读性。

打包配置（build） 决定生产产物的输出目录与优化策略（压缩、分包等）。

jsxRuntime: 'automatic' 让 React 17+ 无需在每个文件手动 import React。

Fast Refresh 提供开发热更新，但仅适用于客户端渲染（CSR），不支持 SSR。

一、它到底是什么

vite.config.js 是 Vite 脚手架的配置文件，相当于项目的总设计蓝图。它用 defineConfig 包裹一个配置对象导出，Vite 在启动时会读取它来初始化开发服务器和打包流程。

js 复制代码

import { defineConfig } from 'vite'

// defineConfig 只做类型提示，不改动运行时
export default defineConfig({
  // 三大核心都写在这里面
  plugins: [],       // 插件系统
  resolve: {},       // 路径别名
  build: {},         // 打包配置
})

它管的三件大事：

核心模块	配置字段	负责什么
插件系统	`plugins`	扩展功能：框架支持、语法转换、热更新
路径别名	`resolve.alias`	把符号映射到真实目录，简化导入
打包配置	`build`	生产产物的输出与优化

二、插件系统：工种调度

插件就像工地上的不同工种，有的负责搬砖（转译代码），有的负责质检（类型检查），各司其职。Vite 本身很轻，能力几乎都靠插件叠加。

2.1 一键启动 React

最常用的 @vitejs/plugin-react，默认无参数调用就能让项目跑起 React：

js 复制代码

import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()], // 无参即可，开箱即用
})

2.2 jsxRuntime: automatic ------ 免写 import React

React 19 引入了全新的 JSX 转换，jsxRuntime: automatic 模式下，编译器自动注入 JSX 运行时 ，你不再需要在每个文件顶部写 import React from 'react'。

js 复制代码

react({
  jsxRuntime: 'automatic', // React 17+ 默认即此模式，显式写出便于理解
})

模式	是否需 `import React`	适用版本
`classic`	每个使用 JSX 的文件都要	React 16 及旧代码
`automatic`	不需要	React 17+（Vite 默认）

2.3 Babel 的角色

Babel 是 JavaScript 编译器，负责把现代语法（JSX、TS、新特性）转成浏览器兼容的代码。@vitejs/plugin-react 内部默认使用 Babel 来完成 JSX/TS 转换和 Fast Refresh 注入。

如果你追求更快的冷启动，可换用 @vitejs/plugin-react-swc（基于 Rust 的 SWC，不用 Babel，速度更快，但部分 Babel 专属插件生态受限）。

维度	@vitejs/plugin-react（Babel）	@vitejs/plugin-react-swc
转译器	Babel	SWC（Rust）
速度	较慢	更快
Fast Refresh	支持	支持
生态	Babel 插件丰富（如 emotion）	轻量

2.4 emotion：CSS-in-JS 性能优化

当你用 @emotion/react 写样式时，配合它的 Babel 插件可以在编译期收集样式，减少运行时开销：

js 复制代码

react({
  jsxImportSource: '@emotion/react',
  babel: {
    plugins: ['@emotion/babel-plugin'], // 编译期优化 CSS-in-JS
  },
})

2.5 Fast Refresh：开发热更新

@vitejs/plugin-react 内置了 React Fast Refresh，修改组件后无需刷新整页即可热更新状态。注意它的边界：

仅适用于客户端渲染（CSR）；
不支持 SSR（服务端渲染需要额外处理，或改用对应的 SWC 方案）。

三、路径别名：给导入"取近道"

3.1 痛点

没有别名时，深层嵌套目录的导入路径又长又脆弱：

js 复制代码

import Button from '../../../../components/Button' // 逐级 ../ 返祖式写法

3.2 配置：ESM 写法（推荐）

Vite 运行在 ESM 环境，没有 __dirname ，所以要用 import.meta.url + fileURLToPath 拿到基于项目根目录的绝对路径：

js 复制代码

import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),          // 业务代码
      '~': fileURLToPath(new URL('./src/assets', import.meta.url)),   // 静态资源
      '#': fileURLToPath(new URL('./src/types', import.meta.url)),    // TS 类型/配置
    },
  },
})

new URL('./src', import.meta.url) 得到 file:// 协议的 URL，fileURLToPath 再把它转成系统绝对路径字符串------因为 Vite 底层的 esbuild/rollup 需要真实路径才能解析。

3.3 前缀约定（建议规范）

在 JS / TS 中使用：

js 复制代码

import Button from '@/components/Button'
import type { User } from '#/user'

在 CSS 中使用（Vite 推荐直接用已配置的别名，不必加 ~/ 前缀）：

css 复制代码

.logo {
  background: url('@/assets/logo.png');
}

动态拼接也是支持的，但 Vite 需要能静态分析 出大致路径，推荐配合 import.meta.glob 处理真正动态的场景：

js 复制代码

// 静态可分析的动态导入
const mod = await import(`@/views/${name}`)

// 真正 Glob 批量导入（Vite 原生支持）
const modules = import.meta.glob('@/components/*.vue')

四、打包配置：生产产物的塑造者

build 字段决定最终生产环境产物的输出方式与优化策略。

js 复制代码

export default defineConfig({
  build: {
    outDir: 'dist',             // 产物输出目录
    sourcemap: false,           // 生产环境建议关闭
    rollupOptions: {
      output: {
        manualChunks: {         // 手动分包，把体积大的库拆出去
          vendor: ['react', 'react-dom'],
        },
      },
    },
  },
})

一句话：plugins 管"怎么转"，resolve.alias 管"去哪找"，build 管"出来长啥样"。 三者合力，构成 vite.config.js 这个"工地指挥中心"。

五、可视化图解：三大核心架构

下面这张图把 vite.config.js 的三大核心及关键项分类呈现。

六、完整流程串联：一次请求如何被"指挥中心"调度

java 复制代码

源码 main.jsx
    │
    ▼
resolve.alias 解析 "@/" 等别名 → 找到真实文件
    │
    ▼
plugins 接管：@vitejs/plugin-react
    ├─ Babel 把 JSX/TS 转成 JS
    ├─ jsxRuntime:automatic 注入运行时（免 import React）
    ├─ emotion 编译期收集样式
    └─ Fast Refresh 监听改动热更新
    │
    ▼
开发：dev server 直接交付浏览器
生产：build 按配置输出 dist（压缩 / 分包）

ASCII 版：

css 复制代码

main.jsx
   │  resolve.alias (@/ → src)
   ▼
plugins:[react()]  ──►  Babel 转译 + automatic + emotion + Fast Refresh
   │
   ├─ dev  ──►  浏览器（热更新）
   └─ build ──► dist/（outDir + 压缩 + manualChunks）