vue3教程：vite.config.ts文件说明-马育民老师

# 介绍

`vite.config.ts` 是 Vite 项目的 **核心配置文件**，位于项目根目录，用于自定义 Vite 的开发服务器、构建流程、插件集成、路径解析、资源优化等行为。采用 TypeScript 编写，通过 `defineConfig` 包裹可获得完整类型提示。

在根目录下，如下图：

[![](https://www.malaoshi.top/upload/0/0/1GW3MyaIwvis.png)](https://www.malaoshi.top/upload/0/0/1GW3MyaIwvis.png)

# 基础结构
```typescript
import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

// 支持环境变量与模式区分
export default defineConfig(({ mode }) => {
  // 加载对应模式的环境变量（.env.development / .env.production）
  const env = loadEnv(mode, process.cwd(), '')

return {
    // 1. 基础配置
    root: process.cwd(),
    base: '/',

// 2. 插件配置
    plugins: [vue()],

// 3. 模块解析
    resolve: {
      alias: {
        '@': path.resolve(__dirname, './src')
      }
    },

// 4. 开发服务器
    server: {
      port: 5173,
      open: true
    },

// 5. 构建配置
    build: {
      outDir: 'dist'
    }
  }
})
```

# 配置项详解

### 1. 基础配置（Root & Base）
```typescript
export default defineConfig({
  // 项目根目录（默认：当前工作目录）
  root: process.cwd(),

// 基础公共路径（部署到子目录时用，如 '/my-app/'）
  base: '/',

// 模式（development / production）
  mode: 'development',

// 全局常量定义（编译时替换）
  define: {
    __APP_VERSION__: JSON.stringify('1.0.0'),
    'import.meta.env.VITE_API_URL': JSON.stringify('https://api.example.com')
  },

// 公共资源目录（存放不打包的静态文件）
  publicDir: 'public',

// 清空控制台（默认：true）
  clearScreen: true
})
```

### 2. 插件配置（Plugins）
Vite 插件用于扩展功能（框架支持、CSS 处理、自动导入等）。
```typescript
import vue from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'
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: [
    // Vue3 支持
    vue(),
    // JSX/TSX 支持
    vueJsx(),
    // 自动导入 API（无需手动 import）
    AutoImport({
      imports: ['vue', 'vue-router', 'pinia'],
      dts: 'src/auto-imports.d.ts'
    }),
    // 自动导入组件
    Components({
      resolvers: [ElementPlusResolver()],
      dts: 'src/components.d.ts'
    })
  ]
})
```

### 3. 模块解析（Resolve）
配置模块查找规则，**常用路径别名**简化导入。
```typescript
import path from 'path'

export default defineConfig({
  resolve: {
    // 路径别名（@ 指向 src）
    alias: {
      '@': path.resolve(__dirname, './src'),
      'components': path.resolve(__dirname, './src/components'),
      'utils': path.resolve(__dirname, './src/utils')
    },

// 解析优先级（默认：['module', 'jsnext:main', 'main']）
    mainFields: ['module', 'jsnext:main', 'main'],

// 导入时自动补全扩展名
    extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json'],

// 强制预构建依赖（避免重复打包）
    dedupe: ['vue', 'vue-router']
  }
})
```

### 4. 开发服务器（Server）
配置本地开发服务，解决**跨域、端口、代理**等问题。
```typescript
export default defineConfig({
  server: {
    // 端口（默认：5173）
    port: 5173,

// 监听地址（0.0.0.0 允许局域网访问）
    host: '0.0.0.0',

// 启动时自动打开浏览器
    open: true,

// 启用 HTTPS（本地开发）
    https: false,

// 热模块替换（HMR）
    hmr: {
      overlay: true, // 错误覆盖层
      timeout: 3000 // 超时时间
    },

// 代理配置（解决跨域）
    proxy: {
      '/api': {
        target: 'http://localhost:3000', // 后端地址
        changeOrigin: true, // 修改 Origin 头
        rewrite: (path) => path.replace(/^\/api/, '') // 路径重写
      }
    }
  }
})
```

### 5. 构建配置（Build）
控制生产环境打包行为，**优化输出、分包、压缩**。
```typescript
export default defineConfig({
  build: {
    // 输出目录（默认：dist）
    outDir: 'dist',

// 静态资源目录（js/css/img 等）
    assetsDir: 'assets',

// 内联资源大小阈值（小于此值转为 base64）
    assetsInlineLimit: 4096,

// 代码分割（拆分第三方依赖）
    rollupOptions: {
      output: {
        // 分包策略
        manualChunks: {
          vue: ['vue', 'vue-router', 'pinia'],
          vendor: ['axios', 'lodash-es'],
          ui: ['element-plus']
        },
        // 资源命名规则
        assetFileNames: 'assets/[name]-[hash][extname]',
        chunkFileNames: 'assets/js/[name]-[hash].js',
        entryFileNames: 'assets/js/[name]-[hash].js'
      }
    },

// 清空输出目录（默认：true）
    emptyOutDir: true,

// 压缩选项（gzip / brotli）
    compress: 'gzip',

// 目标浏览器（兼容配置）
    target: 'es2015',

// CSS 代码分割（默认：true）
    cssCodeSplit: true,

// CSS 压缩（默认：esbuild）
    cssMinify: 'esbuild'
  }
})
```

# 环境变量与模式

Vite 支持通过 `.env` 文件区分开发/生产环境：

- `.env`：所有环境通用
- `.env.development`：开发环境
- `.env.production`：生产环境

```bash
# .env.development
VITE_API_URL=http://localhost:3000/api
VITE_APP_TITLE=My Dev App

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

在配置中加载：
```typescript
import { loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')
  console.log(env.VITE_API_URL) // 输出对应环境的 API 地址
  return {}
})
```

# 总结
`vite.config.ts` 是 Vite 项目的**配置中枢**，核心能力包括：

- **插件化扩展**：无缝集成 Vue/React、UI 组件库、工具类插件。
- **极速开发体验**：HMR、依赖预构建、按需编译。
- **生产优化**：代码分割、资源压缩、CDN 适配。

原文出处：http://www.malaoshi.top/show_1GW3MyaUlA3t.html