Vite 配置对象 defineConfig

[TOC]

## defineConfig 函数重构

defineConfig 是一个专门用来为 Vite 配置文件提供类型提示和智能感知的工具函数。在它的类型定义中，一共有 **4 个重载**，分别对应了传递不同类型参数的场景：

1.  `defineConfig(config: UserConfig): UserConfig`
2.  `defineConfig(config: Promise<UserConfig>): Promise<UserConfig>`
3.  `defineConfig(config: (env: ConfigEnv) => UserConfig): UserConfig`
4.  `defineConfig(config: (env: ConfigEnv) => Promise<UserConfig>): Promise<UserConfig>`

它们都返回传入的参数本身，本身不进行任何转换，全部作用就是在类型层面为你提供帮助。接下来，我们具体看看每个重载的含义。

### 1. 直接传递配置对象

```typescript
function defineConfig(config: UserConfig): UserConfig
```

**含义**：这是最简单的用法，直接传递一个配置对象 `UserConfig`。它不进行任何转换，主要作用是提供 TypeScript 的类型提示与检查。

**使用示例**：

```javascript
// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: {
    port: 3000
  }
})
```

### 2. 传递一个返回配置对象的 Promise

```typescript
function defineConfig(config: Promise<UserConfig>): Promise<UserConfig>
```

**含义**：如果配置需要从一个异步操作中获取（例如，从远程接口拉取），你可以传递这个异步结果的 `Promise`。`defineConfig` 会识别出这是一个 `Promise` 并返回它，最终会由 Vite 内部等待这个 `Promise` 完成后再使用其内部的对象。

**使用示例**：
```javascript
import { defineConfig } from 'vite'

// 模拟一个异步获取配置的函数
const fetchConfig = async () => {
  const response = await fetch('https://api.example.com/vite-config')
  return response.json()
}

export default defineConfig(fetchConfig())
```

### 3. 传递一个返回配置对象的同步函数

```typescript
function defineConfig(config: (env: ConfigEnv) => UserConfig): UserConfig
```

**含义**：传递一个接收 `ConfigEnv` 参数并**同步**返回配置对象的函数。Vite 会根据当前的运行环境（如开发或构建）动态生成配置。
**`ConfigEnv` 对象包含的参数**：

**使用示例**：

```javascript
import { defineConfig } from 'vite'

export default defineConfig(({ command, mode }) => {
  if (command === 'serve') {
    return {
      // 开发模式下的配置
      server: {
        port: 3000
      }
    }
  } else {
    return {
      // 构建模式下的配置
      build: {
        minify: 'esbuild'
      }
    }
  }
})
```

### 4. 传递一个返回配置对象 Promise 的异步函数

```typescript
function defineConfig(config: (env: ConfigEnv) => Promise<UserConfig>): Promise<UserConfig>
```

**含义**：这是第三种情况的异步版本。配置函数可以是 `async` 的，内部可以包含异步操作，其参数 `ConfigEnv` 与同步版本完全相同。Vite 会等待这个异步函数完成并返回结果。

**使用示例**：

```javascript
import { defineConfig } from 'vite'

export default defineConfig(async ({ command, mode }) => {
  // 执行一些异步操作，如动态读取文件
  const data = await asyncFunction()
  return {
    // 基于异步数据生成配置
    define: {
      __APP_DATA__: data
    }
  }
})
```

> Tips：

> 此外，如果你正在使用 Vitest 进行单元测试，并且遇到了类型报错，可能需要将 `defineConfig` 从`'vitest/config'` 中导入，以确保 `test` 等 Vitest 专属配置字段的类型能够被正确识别。
```
import { defineConfig } from 'vitest/config'
```

## vite 配置对象 defineConfig 属性说明

### 1. 顶级配置 (Shared Options)

### 2. 常用子配置详解

为了更好地理解，我将一些常用的子配置进行了详细拆解：

#### 2.1. build 构建选项

#### 2.2. server 开发服务器选项

#### 2.3. resolve 模块解析选项

#### 2.4. css 样式处理选项

#### 2.5. optimizeDeps 依赖优化选项

#### 2.6. ssr 服务端渲染选项

#### 2.7. preview 预览服务器选项