Back to Details

vite-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vite

Vite

Based on Vite 8.0 stable (March 2026). Vite 8 uses Rolldown bundler and Oxc transformer, replacing esbuild + Rollup.
Vite is a next-generation frontend build tool with fast dev server (native ESM + HMR) and optimized production builds powered by Rolldown.
基于Vite 8.0稳定版（2026年3月）。Vite 8采用Rolldown打包器和Oxc转换器，替代了原有的esbuild + Rollup组合。
Vite是下一代前端构建工具，拥有快速的开发服务器（原生ESM + HMR）和基于Rolldown优化的生产构建能力。

Key Vite 8 Changes

Vite 8主要变更

Vite 8 replaces the dual esbuild+Rollup architecture with Rolldown (unified Rust-based bundler) and Oxc (transformer/minifier). A compatibility layer auto-converts old 
esbuild
and 
rollupOptions
configs, but both are deprecated — always use the new names in new code:
Deprecated (still works)Replacement
build.rollupOptions
build.rolldownOptions
esbuild
oxc
optimizeDeps.esbuildOptions
optimizeDeps.rolldownOptions
build.minify: 'esbuild'
build.minify: 'oxc'
(default)
Vite 8用Rolldown（基于Rust的统一打包器）和Oxc（转换器/压缩器）替代了原有的esbuild+Rollup双架构。兼容层会自动转换旧的
esbuild
和
rollupOptions
配置，但两者均已被弃用——在新代码中请务必使用新名称：
已弃用（仍可使用）替代方案
build.rollupOptions
build.rolldownOptions
esbuild
oxc
optimizeDeps.esbuildOptions
optimizeDeps.rolldownOptions
build.minify: 'esbuild'
build.minify: 'oxc'
（默认值）

Preferences

推荐实践

  • Use TypeScript: prefer 
    vite.config.ts
  • Always use ESM — avoid CommonJS
  • Use 
    import.meta.dirname
    (ESM) not 
    __dirname
    (CJS) in config files
  • Use 
    rolldownOptions
    not 
    rollupOptions
    in new code
  • Use 
    oxc
    not 
    esbuild
    in new code
  • 使用TypeScript：优先选择
    vite.config.ts
  • 始终使用ESM——避免CommonJS
  • 在配置文件中使用
    import.meta.dirname
    （ESM）而非
    __dirname
    （CJS）
  • 在新代码中使用
    rolldownOptions
    而非
    rollupOptions
  • 在新代码中使用
    oxc
    而非
    esbuild

Core

核心内容

TopicDescriptionReference
Configuration
vite.config.ts
, 
defineConfig
, conditional configs, 
loadEnv
, new v8 options		core-config
Features
import.meta.glob
, asset queries, 
import.meta.env
, HMR API, CSS modules		core-features
Plugin APIVite/Rolldown hooks, virtual modules, hook filters, plugin orderingcore-plugin-api
主题描述参考文档
配置
vite.config.ts
、
defineConfig
、条件配置、
loadEnv
、v8新增选项		core-config
特性
import.meta.glob
、资源查询、
import.meta.env
、HMR API、CSS模块		core-features
插件APIVite/Rolldown钩子、虚拟模块、钩子过滤器、插件排序core-plugin-api

Build & SSR

构建与SSR

TopicDescriptionReference
Build & SSRLibrary mode, SSR middleware, 
ssrLoadModule
, multi-page apps, JavaScript API		build-and-ssr
主题描述参考文档
构建与SSR库模式、SSR中间件、
ssrLoadModule
、多页面应用、JavaScript API		build-and-ssr

Advanced

进阶内容

TopicDescriptionReference
Environment APIVite 6+ multi-environment support, custom runtimesenvironment-api
Rolldown MigrationVite 8 migration: complete esbuild→oxc and rollupOptions→rolldownOptions mapping, breaking changesrolldown-migration
主题描述参考文档
环境APIVite 6+多环境支持、自定义运行时environment-api
Rolldown迁移Vite 8迁移：完整的esbuild→oxc和rollupOptions→rolldownOptions映射、破坏性变更rolldown-migration

Quick Reference

快速参考

CLI Commands

CLI命令

bash
vite              # Start dev server
vite build        # Production build
vite preview      # Preview production build
vite build --ssr  # SSR build
bash
vite              # 启动开发服务器
vite build        # 生产构建
vite preview      # 预览生产构建产物
vite build --ssr  # SSR构建

Common Config (Vite 8)

常见配置（Vite 8）

ts
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [],
  resolve: {
    alias: { '@': '/src' },
    tsconfigPaths: true,  // New in v8: auto-resolve TS path aliases
  },
  server: {
    port: 3000,
    proxy: { '/api': 'http://localhost:8080' },
    forwardConsole: true,  // New in v8: browser logs → terminal
  },
  build: {
    target: 'esnext',
    outDir: 'dist',
    rolldownOptions: {},   // NOT rollupOptions
  },
  oxc: {                   // NOT esbuild
    jsx: {
      runtime: 'automatic',
      importSource: 'react',
    },
  },
})
ts
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [],
  resolve: {
    alias: { '@': '/src' },
    tsconfigPaths: true,  // v8新增：自动解析TS路径别名
  },
  server: {
    port: 3000,
    proxy: { '/api': 'http://localhost:8080' },
    forwardConsole: true,  // v8新增：浏览器日志转发至终端
  },
  build: {
    target: 'esnext',
    outDir: 'dist',
    rolldownOptions: {},   // 请勿使用rollupOptions
  },
  oxc: {                   // 请勿使用esbuild
    jsx: {
      runtime: 'automatic',
      importSource: 'react',
    },
  },
})

Official Plugins

官方插件

  • @vitejs/plugin-react
    v6 — React with Oxc transforms (Babel removed)
  • @vitejs/plugin-react-swc
    — React with SWC
  • @vitejs/plugin-vue
    — Vue 3 SFC support
  • @vitejs/plugin-vue-jsx
    — Vue 3 JSX
  • @vitejs/plugin-legacy
    — Legacy browser support
  • @vitejs/plugin-react
    v6 — 基于Oxc转换的React支持（已移除Babel）
  • @vitejs/plugin-react-swc
    — 基于SWC的React支持
  • @vitejs/plugin-vue
    — Vue 3单文件组件支持
  • @vitejs/plugin-vue-jsx
    — Vue 3 JSX支持
  • @vitejs/plugin-legacy
    — 旧版浏览器支持

Oxc JSX Quick Reference

Oxc JSX快速参考

ts
// React (automatic runtime — default)
oxc: { jsx: { runtime: 'automatic', importSource: 'react' } }

// Preact (automatic)
oxc: { jsx: { runtime: 'automatic', importSource: 'preact' } }

// Preact (classic with h/Fragment)
oxc: { jsx: { runtime: 'classic', pragma: 'h', pragmaFrag: 'Fragment' } }

// Auto-inject React import (legacy patterns)
oxc: { jsxInject: `import React from 'react'` }
ts
// React（自动运行时——默认）
oxc: { jsx: { runtime: 'automatic', importSource: 'react' } }

// Preact（自动运行时）
oxc: { jsx: { runtime: 'automatic', importSource: 'preact' } }

// Preact（经典运行时，使用h/Fragment）
oxc: { jsx: { runtime: 'classic', pragma: 'h', pragmaFrag: 'Fragment' } }

// 自动注入React导入（旧模式）
oxc: { jsxInject: `import React from 'react'` }