Vite 配置选项

什么是 Vite
配置文件
一、核心配置选项
二、开发服务器配置
三、构建配置
四、CSS 配置
- 4.1 css.modules
- 4.2 css.preprocessorOptions
五、依赖优化
- 5.1 optimizeDeps.include
- 5.2 optimizeDeps.exclude
六、完整配置示例
七、环境变量
- 7.1 内置环境变量
- 7.2 自定义环境变量
八、常见问题和最佳实践
九、Vite 6.x 新特性
十、总结
参考资源
Sources

什么是 Vite

Vite 是新一代前端构建工具，由 Vue.js 作者尤雨溪开发，提供极速的开发体验和优化的生产构建：

⚡ 极速冷启动：基于原生 ES 模块，无需打包即可启动
🔥 闪电般的 HMR：热模块替换速度与模块数量无关
🛠️ 丰富的功能：开箱即用支持 TypeScript、JSX、CSS 预处理器等
📦 优化的构建：预配置的 Rollup 构建，输出高度优化的静态资源
🔌 通用插件：基于 Rollup 的插件接口，兼容大部分 Rollup 插件
🌐 完全类型化：灵活的 API 和完整的 TypeScript 类型定义

# 创建 Vite 项目
npm create vite@latest

# 或使用特定模板
npm create vite@latest my-vue-app -- --template vue
npm create vite@latest my-react-app -- --template react-ts

版本说明

本文档基于 Vite 5.x 编写，同时包含 Vite 6.x 的新特性说明。

Vite 版本历史：

✅ Vite 6.0（2024-11-26 发布）：
- 新增 Environment API（实验性）
- 支持 Node.js 18、20、22+
- Sass 默认使用 modern API
- 改进 CSS 输出文件名自定义
- npm 下载量：17M+/周
✅ Vite 5.0（2023 年发布）：
- 改进开发服务器性能
- 更好的 CSS 处理
- npm 下载量：7.5M+/周

主要特性：

⚡ 开发环境使用原生 ES 模块，无需打包
📦 生产环境使用 Rollup 打包，输出优化
🔌 兼容 Rollup 插件生态系统
🎯 默认支持 TypeScript、JSX、CSS 预处理器

注意事项

Vite 需要 Node.js 18.0+ 或 20.0+ 版本
开发时基于浏览器原生 ES 模块，需要现代浏览器支持
某些 CommonJS 依赖可能需要预构建优化
SSR 应用需要额外配置

配置文件

Vite 使用 vite.config.js / vite.config.ts 作为配置文件：

# 配置文件位置（按优先级）
vite.config.js
vite.config.ts
vite.config.mjs
vite.config.cjs
vite.config.mts
vite.config.cts

推荐使用 TypeScript 格式（vite.config.ts），本文以 TypeScript 为例。

基本配置结构

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  // 项目根目录
  root: process.cwd(),

  // 基础公共路径
  base: '/',

  // 开发服务器配置
  server: {
    port: 3000,
    open: true
  },

  // 构建配置
  build: {
    outDir: 'dist',
    minify: 'esbuild'
  },

  // 插件
  plugins: [vue()]
})

条件配置

根据命令和模式动态配置：

import { defineConfig } from 'vite'

export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  if (command === 'serve') {
    // 开发环境配置
    return {
      server: {
        port: 3000
      },
      define: {
        __DEV__: true
      }
    }
  } else {
    // 生产环境配置 (command === 'build')
    return {
      build: {
        minify: 'terser',
        sourcemap: true
      },
      define: {
        __DEV__: false
      }
    }
  }
})

参数说明：

参数	类型	说明
`command`	`'serve'` \| `'build'`	开发服务器或生产构建
`mode`	`string`	当前模式（`development` / `production` / 自定义）
`isSsrBuild`	`boolean`	是否为 SSR 构建
`isPreview`	`boolean`	是否为预览服务器

异步配置

import { defineConfig } from 'vite'

export default defineConfig(async ({ command, mode }) => {
  const data = await asyncFunction()

  return {
    // 使用异步数据配置
    define: {
      __API_URL__: JSON.stringify(data.apiUrl)
    }
  }
})

一、核心配置选项

1.1 root

作用：项目根目录（index.html 所在位置）。

{
  root: process.cwd()  // 默认值：当前工作目录
}

使用场景：

// 单页应用
{
  root: './'
}

// 项目在子目录
{
  root: './src'
}

// Monorepo 项目
{
  root: './packages/web'
}

1.2 base

作用：开发或生产环境服务的公共基础路径。

{
  base: '/'  // 默认值
}

影响对比：

// base: '/'（默认）
// 资源路径：/assets/index.js
<script src="/assets/index.js"></script>

// base: '/my-app/'
// 资源路径：/my-app/assets/index.js
<script src="/my-app/assets/index.js"></script>

// base: './'（相对路径）
// 资源路径：./assets/index.js
<script src="./assets/index.js"></script>

使用场景：

// 部署到子路径（如 GitHub Pages）
{
  base: '/my-repo/'
}

// 部署到 CDN
{
  base: 'https://cdn.example.com/'
}

// 相对路径部署
{
  base: './'
}

1.3 mode

作用：指定应用模式，影响环境变量加载。

{
  mode: 'development'  // 或 'production'、自定义模式
}

环境变量文件：

.env                # 所有模式加载
.env.local          # 所有模式加载，git 忽略
.env.[mode]         # 指定模式加载
.env.[mode].local   # 指定模式加载，git 忽略

优先级：mode 特定文件 > 通用文件，.local > 非 .local

示例：

# .env.development
VITE_API_URL=http://localhost:3000
VITE_APP_TITLE=My App (Dev)

# .env.production
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My App

// 在代码中使用
console.log(import.meta.env.VITE_API_URL)
console.log(import.meta.env.VITE_APP_TITLE)

1.4 define

作用：定义全局常量替换。

{
  define: {
    __APP_VERSION__: JSON.stringify('1.0.0'),
    __DEV__: true,
    'process.env.NODE_ENV': JSON.stringify('production')
  }
}

影响对比：

// 配置
{
  define: {
    __API_URL__: JSON.stringify('https://api.example.com')
  }
}

// 源代码
console.log(__API_URL__)

// 编译后
console.log('https://api.example.com')

注意事项

值会被直接插入到代码中，字符串需要 JSON.stringify()
替换是简单的文本替换，不会解析语法
避免定义与全局变量冲突的名称

1.5 plugins

作用：配置插件数组。

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

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

常用插件：

{
  plugins: [
    // Vue
    vue(),
    vueJsx(),

    // React
    react(),

    // 自动导入
    AutoImport({
      imports: ['vue', 'vue-router']
    }),

    // 组件自动注册
    Components({
      resolvers: [ElementPlusResolver()]
    }),

    // 传统浏览器支持
    legacy({
      targets: ['defaults', 'not IE 11']
    })
  ]
}

条件应用插件：

{
  plugins: [
    vue(),
    // 仅在生产环境使用
    process.env.NODE_ENV === 'production' && visualizer(),
    // 仅在构建时使用
    {
      ...legacy(),
      apply: 'build'
    }
  ].filter(Boolean)
}

1.6 resolve.alias

作用：定义路径别名。

import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components'),
      '@utils': path.resolve(__dirname, './src/utils'),
      '~': path.resolve(__dirname, './'),
    }
  }
})

影响对比：

// ❌ 不使用别名
import Button from '../../../components/Button.vue'
import { formatDate } from '../../../utils/date'

// ✅ 使用别名
import Button from '@components/Button.vue'
import { formatDate } from '@utils/date'

TypeScript 配置：

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

1.7 resolve.extensions

作用：导入时省略的扩展名列表。

{
  resolve: {
    extensions: ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']  // 默认值
  }
}

影响对比：

// 配置 extensions: ['.js', '.ts', '.vue']

// ✅ 可以省略扩展名
import Button from './Button'  // 自动解析 Button.vue
import utils from './utils'    // 自动解析 utils.ts

// ❌ 未配置的扩展名必须显式指定
import data from './data.json'  // 必须写 .json

注意事项

不建议忽略自定义导入类型（如 .vue）的扩展名
可能影响 IDE 和类型支持

1.8 publicDir

作用：静态资源目录，不会被构建处理，直接复制到输出目录。

{
  publicDir: 'public'  // 默认值
}

使用场景：

public/
├── favicon.ico
├── robots.txt
└── images/
    └── logo.png

访问方式：

<!-- 直接使用绝对路径，不需要导入 -->
<img src="/images/logo.png" alt="Logo">
<link rel="icon" href="/favicon.ico">

影响对比：

// 普通资源（需要导入）
import logo from './assets/logo.png'
<img src={logo} />

// public 资源（直接引用）
<img src="/logo.png" />

何时使用 public

文件名不需要 hash
文件被数千个文件引用
文件路径必须固定（如 robots.txt）

二、开发服务器配置

2.1 server.port

作用：开发服务器端口。

{
  server: {
    port: 3000,  // 默认：5173
    strictPort: false  // 端口被占用时是否直接退出
  }
}

影响对比：

# port: 5173（默认）
VITE v5.4.21  ready in 320 ms
➜  Local:   http://localhost:5173/

# port: 3000
VITE v5.4.21  ready in 320 ms
➜  Local:   http://localhost:3000/

# strictPort: true 且端口被占用
Error: Port 3000 is already in use

2.2 server.host

作用：指定服务器监听的 IP 地址。

{
  server: {
    host: '0.0.0.0'  // 监听所有地址
    // host: 'localhost'  // 默认，仅本地访问
    // host: true  // 等同于 '0.0.0.0'
  }
}

使用场景：

// 仅本地开发
{
  server: {
    host: 'localhost'  // http://localhost:3000
  }
}

// 局域网访问（移动端调试）
{
  server: {
    host: '0.0.0.0'  // http://192.168.1.100:3000
  }
}

2.3 server.open

作用：启动时自动在浏览器打开。

{
  server: {
    open: true,  // 打开默认页面
    // open: '/docs',  // 打开指定路径
    // open: '/docs/index.html'
  }
}

2.4 server.proxy

作用：配置开发服务器代理，解决跨域问题。

{
  server: {
    proxy: {
      // 字符串简写
      '/foo': 'http://localhost:4567',

      // 带选项的完整配置
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      },

      // 使用正则表达式
      '^/fallback/.*': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/fallback/, '')
      },

      // WebSocket 代理
      '/socket.io': {
        target: 'ws://localhost:5174',
        ws: true,
        rewriteWsOrigin: true
      }
    }
  }
}

实际应用：

// 开发环境代理配置
{
  server: {
    proxy: {
      '/api': {
        target: 'https://api.example.com',
        changeOrigin: true,
        secure: false,  // 允许 HTTPS 自签名证书
        rewrite: (path) => path.replace(/^\/api/, '/v1')
      }
    }
  }
}

// 前端请求
fetch('/api/users')  // → https://api.example.com/v1/users

2.5 server.cors

作用：配置 CORS。

{
  server: {
    cors: true  // 启用默认 CORS
    // 或自定义配置
    // cors: {
    //   origin: 'http://localhost:3001',
    //   credentials: true
    // }
  }
}

2.6 server.fs

作用：限制文件系统访问。

import { defineConfig, searchForWorkspaceRoot } from 'vite'

export default defineConfig({
  server: {
    fs: {
      // 允许访问的目录
      allow: [
        searchForWorkspaceRoot(process.cwd()),
        '/path/to/custom/directory'
      ],
      // 禁止访问的文件
      deny: ['.env', '.env.*', '*.{crt,pem}']
    }
  }
})

2.7 server.warmup

作用：预热常用文件，提升首次加载速度。

{
  server: {
    warmup: {
      clientFiles: [
        './src/components/*.vue',
        './src/utils/big-utils.js'
      ],
      ssrFiles: [
        './src/server/modules/*.js'
      ]
    }
  }
}

三、构建配置

3.1 build.outDir

作用：指定输出目录。

{
  build: {
    outDir: 'dist',  // 默认值
    emptyOutDir: true  // 构建前清空目录
  }
}

3.2 build.target

作用：设置浏览器兼容性目标。

{
  build: {
    target: 'esnext',  // 默认值
    // target: 'es2015',  // 支持旧浏览器
    // target: ['chrome87', 'firefox78', 'safari14']  // 指定浏览器版本
  }
}

3.3 build.minify

作用：代码压缩方式。

{
  build: {
    minify: 'esbuild',  // 默认值，使用 esbuild（更快）
    // minify: 'terser',  // 使用 terser（压缩率更高）
    // minify: false,  // 不压缩

    // terser 选项（仅在 minify: 'terser' 时生效）
    terserOptions: {
      compress: {
        drop_console: true,  // 删除 console
        drop_debugger: true  // 删除 debugger
      }
    }
  }
}

3.4 build.sourcemap

作用：生成 source map。

{
  build: {
    sourcemap: false,  // 默认值，不生成
    // sourcemap: true,  // 生成独立 .map 文件
    // sourcemap: 'inline',  // 内联到文件中
    // sourcemap: 'hidden'  // 生成但不引用
  }
}

3.5 build.rollupOptions

作用：自定义 Rollup 打包配置。

{
  build: {
    rollupOptions: {
      // 外部化依赖（不打包）
      external: ['vue', 'vue-router'],

      // 输出配置
      output: {
        // 分包策略
        manualChunks: {
          'vendor': ['vue', 'vue-router'],
          'utils': ['lodash-es', 'dayjs']
        },

        // 文件命名
        chunkFileNames: 'js/[name]-[hash].js',
        entryFileNames: 'js/[name]-[hash].js',
        assetFileNames: '[ext]/[name]-[hash].[ext]'
      }
    }
  }
}

高级分包策略：

{
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          // 将 node_modules 中的包分离
          if (id.includes('node_modules')) {
            return 'vendor'
          }

          // 按目录分包
          if (id.includes('/src/views/')) {
            return 'views'
          }
          if (id.includes('/src/components/')) {
            return 'components'
          }
        }
      }
    }
  }
}

3.6 build.assetsInlineLimit

作用：小于此大小的资源将内联为 base64。

{
  build: {
    assetsInlineLimit: 4096  // 默认 4KB
  }
}

影响对比：

// assetsInlineLimit: 4096

// 小文件（<4KB）- 内联
import smallIcon from './small-icon.png'
// 编译为：data:image/png;base64,iVBORw0KG...

// 大文件（>4KB）- 外部文件
import logo from './logo.png'
// 编译为：/assets/logo.a3b4c5d6.png

四、CSS 配置

4.1 css.modules

作用：配置 CSS Modules。

{
  css: {
    modules: {
      // 生成的类名格式
      generateScopedName: '[name]__[local]___[hash:base64:5]',
      // 命名转换
      localsConvention: 'camelCaseOnly',
      // 全局模块路径
      globalModulePaths: [/global\.module\.css$/]
    }
  }
}

使用示例：

/* Button.module.css */
.button {
  background: blue;
}

.primaryButton {
  background: red;
}

import styles from './Button.module.css'

// localsConvention: 'camelCaseOnly'
console.log(styles.button)  // "Button__button___a1b2c"
console.log(styles.primaryButton)  // "Button__primaryButton___d3e4f"

4.2 css.preprocessorOptions

作用：配置 CSS 预处理器选项。

{
  css: {
    preprocessorOptions: {
      // SCSS
      scss: {
        api: 'modern-compiler',  // Vite 5.4+
        additionalData: `@import "@/styles/variables.scss";`,
        // 自动导入变量到每个 scss 文件
        includePaths: ['node_modules']
      },

      // Less
      less: {
        math: 'parens-division',
        globalVars: {
          primary: '#1890ff'
        }
      },

      // Stylus
      styl: {
        define: {
          $specialColor: new stylus.nodes.RGBA(51, 197, 255, 1)
        }
      }
    }
  }
}

五、依赖优化

5.1 optimizeDeps.include

作用：强制预构建的依赖。

{
  optimizeDeps: {
    include: [
      'vue',
      'vue-router',
      'pinia',
      'axios',
      // 嵌套依赖
      'esm-dep > cjs-dep'
    ]
  }
}

使用场景：

// 动态导入的依赖需要手动包含
{
  optimizeDeps: {
    include: [
      'lodash-es',  // 动态导入：() => import('lodash-es')
    ]
  }
}

5.2 optimizeDeps.exclude

作用：排除预构建的依赖。

{
  optimizeDeps: {
    exclude: [
      'your-package-name',  // 本地开发的包
      '@my-scope/internal-lib'
    ]
  }
}

六、完整配置示例

6.1 Vue 3 + TypeScript 项目

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'
import path from 'path'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  plugins: [
    vue(),
    vueJsx(),
    AutoImport({
      imports: ['vue', 'vue-router', 'pinia'],
      resolvers: [ElementPlusResolver()],
      dts: 'src/auto-imports.d.ts'
    }),
    Components({
      resolvers: [ElementPlusResolver()],
      dts: 'src/components.d.ts'
    })
  ],

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

  server: {
    port: 3000,
    open: true,
    host: '0.0.0.0',
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  },

  build: {
    outDir: 'dist',
    sourcemap: false,
    minify: 'esbuild',
    rollupOptions: {
      output: {
        manualChunks: {
          'vue-vendor': ['vue', 'vue-router', 'pinia'],
          'element-plus': ['element-plus'],
          'utils': ['axios', 'dayjs']
        },
        chunkFileNames: 'js/[name]-[hash].js',
        entryFileNames: 'js/[name]-[hash].js',
        assetFileNames: '[ext]/[name]-[hash].[ext]'
      }
    }
  },

  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        additionalData: `@use "@/styles/variables.scss" as *;`
      }
    }
  }
})

6.2 React + TypeScript 项目

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [
    react({
      // React Fast Refresh
      fastRefresh: true,
      // Babel 配置
      babel: {
        plugins: [
          ['@babel/plugin-proposal-decorators', { legacy: true }]
        ]
      }
    })
  ],

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

  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'https://api.example.com',
        changeOrigin: true,
        secure: false
      }
    }
  },

  build: {
    target: 'es2015',
    minify: 'terser',
    terserOptions: {
      compress: {
        drop_console: true,
        drop_debugger: true
      }
    },
    rollupOptions: {
      output: {
        manualChunks: {
          'react-vendor': ['react', 'react-dom', 'react-router-dom'],
          'ui-vendor': ['antd', '@ant-design/icons']
        }
      }
    }
  },

  esbuild: {
    jsxFactory: 'React.createElement',
    jsxFragment: 'React.Fragment'
  }
})

6.3 库模式配置

// vite.config.ts
import { defineConfig } from 'vite'
import { resolve } from 'path'

export default defineConfig({
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'MyLib',
      formats: ['es', 'cjs', 'umd'],
      fileName: (format) => `my-lib.${format}.js`
    },
    rollupOptions: {
      // 外部化依赖（不打包到库中）
      external: ['vue', 'react'],
      output: {
        globals: {
          vue: 'Vue',
          react: 'React'
        }
      }
    }
  }
})

七、环境变量

7.1 内置环境变量

// 在代码中访问
console.log(import.meta.env.MODE)  // 'development' 或 'production'
console.log(import.meta.env.BASE_URL)  // 基础 URL
console.log(import.meta.env.PROD)  // 是否为生产环境
console.log(import.meta.env.DEV)  // 是否为开发环境
console.log(import.meta.env.SSR)  // 是否为 SSR

7.2 自定义环境变量

文件结构：

.env                # 所有模式
.env.local          # 所有模式，git 忽略
.env.development    # 开发模式
.env.production     # 生产模式
.env.staging        # 自定义 staging 模式

示例：

# .env
VITE_APP_TITLE=My App
VITE_APP_VERSION=1.0.0

# .env.development
VITE_API_URL=http://localhost:3000/api
VITE_DEBUG=true

# .env.production
VITE_API_URL=https://api.example.com
VITE_DEBUG=false

TypeScript 类型定义：

// src/env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  readonly VITE_API_URL: string
  readonly VITE_DEBUG: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

在代码中使用：

const apiUrl = import.meta.env.VITE_API_URL
const isDebug = import.meta.env.VITE_DEBUG === 'true'

console.log(`App: ${import.meta.env.VITE_APP_TITLE}`)

八、常见问题和最佳实践

8.1 性能优化

1. 依赖预构建：

{
  optimizeDeps: {
    include: [
      // 提前包含大型依赖
      'lodash-es',
      'element-plus'
    ]
  }
}

2. 构建优化：

{
  build: {
    // 使用 esbuild 压缩（更快）
    minify: 'esbuild',

    // 分包策略
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) {
            // 将大型库分离
            if (id.includes('element-plus')) {
              return 'element-plus'
            }
            if (id.includes('echarts')) {
              return 'echarts'
            }
            return 'vendor'
          }
        }
      }
    },

    // 关闭 sourcemap（生产环境）
    sourcemap: false
  }
}

8.2 Monorepo 配置

import { defineConfig } from 'vite'
import { resolve } from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@my-org/shared': resolve(__dirname, '../shared/src')
    }
  },

  server: {
    fs: {
      // 允许访问 monorepo 根目录
      allow: ['../..']
    }
  },

  optimizeDeps: {
    // 排除 workspace 包
    exclude: ['@my-org/shared']
  }
})

8.3 生产环境检查清单

{
  build: {
    // ✅ 启用代码压缩
    minify: 'esbuild',

    // ✅ 删除 console（可选）
    terserOptions: {
      compress: {
        drop_console: true
      }
    },

    // ✅ 关闭 sourcemap（或使用 'hidden'）
    sourcemap: false,

    // ✅ 合理的分包策略
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['vue', 'vue-router']
        }
      }
    }
  },

  // ✅ 设置正确的 base
  base: '/my-app/',

  define: {
    // ✅ 替换生产环境变量
    __DEV__: false
  }
}

8.4 常见错误解决

1. 依赖预构建失败：

{
  optimizeDeps: {
    include: ['problematic-package'],
    // 强制重新预构建
    force: true
  }
}

2. CSS 导入顺序问题：

// 确保全局样式在组件样式之前导入
// main.ts
import './styles/reset.css'  // 先导入全局样式
import './styles/global.css'
import App from './App.vue'  // 后导入组件

3. 路径别名 TypeScript 报错：

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

九、Vite 6.x 新特性

9.1 Environment API（实验性）

Vite 6.0 引入了 Environment API，主要面向框架作者，用于支持多环境开发：

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  environments: {
    client: {
      // 浏览器环境配置
    },
    ssr: {
      // SSR 环境配置
    },
    worker: {
      // Web Worker 环境配置
    }
  }
})

9.2 Node.js 支持更新

✅ 支持 Node.js 18、20、22+
❌ 移除 Node.js 21 支持

9.3 Sass Modern API

{
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',  // 默认使用现代 API
        // api: 'legacy'  // 使用旧版 API
      }
    }
  }
}

十、总结

必须配置的选项

plugins - 框架支持（Vue/React 等）
resolve.alias - 路径别名
server.port - 开发服务器端口
server.proxy - API 代理配置
build.outDir - 构建输出目录
base - 部署基础路径

常用命令

# 开发服务器
npm run dev
vite

# 生产构建
npm run build
vite build

# 预览生产构建
npm run preview
vite preview

# 使用自定义配置文件
vite --config vite.custom.config.js

# 指定模式
vite --mode staging

# 清除依赖预构建缓存
vite --force

参考资源

⚡ 使用 Vite，享受极速的开发体验！

Vite 配置选项

什么是 Vite #

配置文件 #

基本配置结构 #

条件配置 #

异步配置 #

一、核心配置选项 #

1.1 root #

1.2 base #

1.3 mode #

1.4 define #

1.5 plugins #

1.6 resolve.alias #

1.7 resolve.extensions #

1.8 publicDir #

二、开发服务器配置 #

2.1 server.port #

2.2 server.host #

2.3 server.open #

2.4 server.proxy #

2.5 server.cors #

2.6 server.fs #

2.7 server.warmup #

三、构建配置 #

3.1 build.outDir #

3.2 build.target #

3.3 build.minify #

3.4 build.sourcemap #

3.5 build.rollupOptions #

3.6 build.assetsInlineLimit #

四、CSS 配置 #

4.1 css.modules #

4.2 css.preprocessorOptions #

五、依赖优化 #

5.1 optimizeDeps.include #

5.2 optimizeDeps.exclude #

六、完整配置示例 #

6.1 Vue 3 + TypeScript 项目 #

6.2 React + TypeScript 项目 #

6.3 库模式配置 #

七、环境变量 #

7.1 内置环境变量 #

7.2 自定义环境变量 #

八、常见问题和最佳实践 #

8.1 性能优化 #

8.2 Monorepo 配置 #

8.3 生产环境检查清单 #

8.4 常见错误解决 #

九、Vite 6.x 新特性 #

9.1 Environment API（实验性） #

9.2 Node.js 支持更新 #

9.3 Sass Modern API #

十、总结 #

必须配置的选项 #

推荐工作流 #

常用命令 #

参考资源 #

Sources #

什么是 Vite

配置文件

基本配置结构

条件配置

异步配置

一、核心配置选项

1.1 root

1.2 base

1.3 mode

1.4 define

1.5 plugins

1.6 resolve.alias

1.7 resolve.extensions

1.8 publicDir

二、开发服务器配置

2.1 server.port

2.2 server.host

2.3 server.open

2.4 server.proxy

2.5 server.cors

2.6 server.fs

2.7 server.warmup

三、构建配置

3.1 build.outDir

3.2 build.target

3.3 build.minify

3.4 build.sourcemap

3.5 build.rollupOptions

3.6 build.assetsInlineLimit

四、CSS 配置

4.1 css.modules

4.2 css.preprocessorOptions

五、依赖优化

5.1 optimizeDeps.include

5.2 optimizeDeps.exclude

六、完整配置示例

6.1 Vue 3 + TypeScript 项目

6.2 React + TypeScript 项目

6.3 库模式配置

七、环境变量

7.1 内置环境变量

7.2 自定义环境变量

八、常见问题和最佳实践

8.1 性能优化

8.2 Monorepo 配置

8.3 生产环境检查清单

8.4 常见错误解决

九、Vite 6.x 新特性

9.1 Environment API（实验性）

9.2 Node.js 支持更新

9.3 Sass Modern API

十、总结

必须配置的选项

推荐工作流

常用命令

参考资源

Sources