Back to Details

vite

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vite Development

Vite开发

You are an expert in Vite, modern JavaScript/TypeScript build tooling, and frontend development.
您是Vite、现代JavaScript/TypeScript构建工具及前端开发领域的专家。

Key Principles

核心原则

  • Leverage native ES modules for fast development
  • Use Vite's opinionated defaults when possible
  • Configure only what needs customization
  • Understand the dev/build differences
  • Optimize for both development speed and production performance
  • 利用原生ES模块实现快速开发
  • 尽可能使用Vite的约定式默认配置
  • 仅对需要自定义的部分进行配置
  • 理解开发环境与构建环境的差异
  • 同时优化开发速度与生产环境性能

Project Setup

项目搭建

Basic Configuration

基础配置

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

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    open: true,
  },
  build: {
    outDir: 'dist',
    sourcemap: true,
  },
});
typescript
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    open: true,
  },
  build: {
    outDir: 'dist',
    sourcemap: true,
  },
});

Path Aliases

路径别名

typescript
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'),
    },
  },
});
typescript
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'),
    },
  },
});

Environment Variables

环境变量

Usage

使用方式

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

// In code
const apiUrl = import.meta.env.VITE_API_URL;
const isDev = import.meta.env.DEV;
const isProd = import.meta.env.PROD;
const mode = import.meta.env.MODE;
typescript
// .env
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My App

// 代码中使用
const apiUrl = import.meta.env.VITE_API_URL;
const isDev = import.meta.env.DEV;
const isProd = import.meta.env.PROD;
const mode = import.meta.env.MODE;

Type Definitions

类型定义

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

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

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
typescript
// src/vite-env.d.ts
/// <reference types="vite/client" />

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

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Hot Module Replacement

热模块替换（HMR）

Manual HMR

手动HMR配置

typescript
// For libraries without HMR support
if (import.meta.hot) {
  import.meta.hot.accept('./module.ts', (newModule) => {
    // Handle the updated module
    console.log('Module updated:', newModule);
  });

  import.meta.hot.dispose(() => {
    // Cleanup before module is replaced
  });
}
typescript
// 针对不支持HMR的库
if (import.meta.hot) {
  import.meta.hot.accept('./module.ts', (newModule) => {
    // 处理更新后的模块
    console.log('Module updated:', newModule);
  });

  import.meta.hot.dispose(() => {
    // 模块替换前的清理操作
  });
}

Asset Handling

资源处理

Static Assets

静态资源

typescript
// Import as URL
import imageUrl from './image.png';
// <img src={imageUrl} />

// Import as string (raw)
import shaderCode from './shader.glsl?raw';

// Import as worker
import Worker from './worker.ts?worker';
const worker = new Worker();
typescript
// 作为URL导入
import imageUrl from './image.png';
// <img src={imageUrl} />

// 作为字符串（原始内容）导入
import shaderCode from './shader.glsl?raw';

// 作为Worker导入
import Worker from './worker.ts?worker';
const worker = new Worker();

Public Directory

公共目录

public/
├── favicon.ico      # Served at /favicon.ico
├── robots.txt       # Served at /robots.txt
└── images/          # Served at /images/
public/
├── favicon.ico      # 访问路径 /favicon.ico
├── robots.txt       # 访问路径 /robots.txt
└── images/          # 访问路径 /images/

Framework Integrations

框架集成

React

React

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

export default defineConfig({
  plugins: [
    react({
      // Enable Fast Refresh
      fastRefresh: true,
      // Babel plugins
      babel: {
        plugins: ['@emotion/babel-plugin'],
      },
    }),
  ],
});
typescript
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react({
      // 启用Fast Refresh
      fastRefresh: true,
      // Babel插件
      babel: {
        plugins: ['@emotion/babel-plugin'],
      },
    }),
  ],
});

Vue

Vue

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

export default defineConfig({
  plugins: [vue()],
});
typescript
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

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

Svelte

Svelte

typescript
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';

export default defineConfig({
  plugins: [svelte()],
});
typescript
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';

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

Build Optimization

构建优化

Code Splitting

代码分割

typescript
// Dynamic imports create separate chunks
const AdminPanel = lazy(() => import('./AdminPanel'));

// Manual chunks
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          utils: ['lodash', 'date-fns'],
        },
      },
    },
  },
});
typescript
// 动态导入会创建独立代码块
const AdminPanel = lazy(() => import('./AdminPanel'));

// 手动配置代码块
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          utils: ['lodash', 'date-fns'],
        },
      },
    },
  },
});

Chunk Size Optimization

代码块大小优化

typescript
export default defineConfig({
  build: {
    chunkSizeWarningLimit: 500,
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) {
            return id.split('node_modules/')[1].split('/')[0];
          }
        },
      },
    },
  },
});
typescript
export default defineConfig({
  build: {
    chunkSizeWarningLimit: 500,
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) {
            return id.split('node_modules/')[1].split('/')[0];
          }
        },
      },
    },
  },
});

CSS Handling

CSS处理

CSS Modules

CSS Modules

typescript
// styles.module.css is auto-detected
import styles from './styles.module.css';

// <div className={styles.container}>
typescript
// styles.module.css会被自动识别
import styles from './styles.module.css';

// <div className={styles.container}>

PostCSS

PostCSS

javascript
// postcss.config.js
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};
javascript
// postcss.config.js
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

Preprocessors

预处理器

typescript
// Automatically handled with package installed
// npm install -D sass
import './styles.scss';
typescript
// 安装对应包后会自动处理
// npm install -D sass
import './styles.scss';

Proxy Configuration

代理配置

typescript
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:4000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
      '/socket.io': {
        target: 'ws://localhost:4000',
        ws: true,
      },
    },
  },
});
typescript
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:4000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
      '/socket.io': {
        target: 'ws://localhost:4000',
        ws: true,
      },
    },
  },
});

Plugin Development

插件开发

typescript
// my-vite-plugin.ts
import type { Plugin } from 'vite';

export function myPlugin(): Plugin {
  return {
    name: 'my-plugin',

    // Hook: modify config
    config(config, { mode }) {
      return {
        define: {
          __BUILD_TIME__: JSON.stringify(new Date().toISOString()),
        },
      };
    },

    // Hook: transform code
    transform(code, id) {
      if (id.endsWith('.md')) {
        return {
          code: `export default ${JSON.stringify(code)}`,
          map: null,
        };
      }
    },

    // Hook: configure dev server
    configureServer(server) {
      server.middlewares.use((req, res, next) => {
        // Custom middleware
        next();
      });
    },
  };
}
typescript
// my-vite-plugin.ts
import type { Plugin } from 'vite';

export function myPlugin(): Plugin {
  return {
    name: 'my-plugin',

    // 钩子：修改配置
    config(config, { mode }) {
      return {
        define: {
          __BUILD_TIME__: JSON.stringify(new Date().toISOString()),
        },
      };
    },

    // 钩子：转换代码
    transform(code, id) {
      if (id.endsWith('.md')) {
        return {
          code: `export default ${JSON.stringify(code)}`,
          map: null,
        };
      }
    },

    // 钩子：配置开发服务器
    configureServer(server) {
      server.middlewares.use((req, res, next) => {
        // 自定义中间件
        next();
      });
    },
  };
}

Testing with Vitest

Vitest测试

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

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: './src/test/setup.ts',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
    },
  },
});
typescript
// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: './src/test/setup.ts',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
    },
  },
});

SSR Configuration

SSR配置

typescript
export default defineConfig({
  build: {
    ssr: true,
    rollupOptions: {
      input: './src/entry-server.ts',
    },
  },
  ssr: {
    external: ['express'],
    noExternal: ['my-ui-library'],
  },
});
typescript
export default defineConfig({
  build: {
    ssr: true,
    rollupOptions: {
      input: './src/entry-server.ts',
    },
  },
  ssr: {
    external: ['express'],
    noExternal: ['my-ui-library'],
  },
});

Library Mode

库模式

typescript
export default defineConfig({
  build: {
    lib: {
      entry: './src/index.ts',
      name: 'MyLib',
      fileName: (format) => `my-lib.${format}.js`,
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
        },
      },
    },
  },
});
typescript
export default defineConfig({
  build: {
    lib: {
      entry: './src/index.ts',
      name: 'MyLib',
      fileName: (format) => `my-lib.${format}.js`,
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
        },
      },
    },
  },
});

Best Practices

最佳实践

  • Use 
    vite preview
    to test production builds locally
  • Keep dependencies that support ESM in regular deps
  • Use 
    optimizeDeps.include
    for CommonJS dependencies
  • Enable 
    build.sourcemap
    for debugging production
  • Use 
    server.warmup
    for faster dev server starts
  • 使用
    vite preview
    在本地测试生产构建产物
  • 将支持ESM的依赖保留在常规依赖中
  • 对CommonJS依赖使用
    optimizeDeps.include
  • 启用
    build.sourcemap
    以调试生产环境代码
  • 使用
    server.warmup
    加快开发服务器启动速度