Vite 配置选项介绍

Vite 配置说明

[TOC]

## Vite 配置选项介绍

> Tips：Vite需要依赖nodejs环境

### 1. 一份完整你vite配置文件示例

一份**完整、通用、可直接复制使用**的 `vite.config.js`，包含常用配置：开发代理、端口、路径别名、打包配置、环境变量等，开箱即用。

```js
import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

// https://vite.dev/config/
export default defineConfig(({ command, mode }) => {
  // 加载环境变量
  const env = loadEnv(mode, process.cwd())

return {
    // 插件
    plugins: [
      vue(), // Vue 项目用，非 Vue 可删掉
    ],

// 路径别名
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src'),
        '@assets': path.resolve(__dirname, 'src/assets'),
        '@components': path.resolve(__dirname, 'src/components'),
      },
    },

// 开发服务器
    server: {
      // 端口
      port: 3000,
      // 自动打开浏览器
      open: true,
      // 允许跨域
      cors: true,
      // 代理配置
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL || 'http://localhost:8080',
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, ''),
        },
      },
    },

// 预览服务（npm run preview）
    preview: {
      port: 3001,
      open: true,
    },

// 构建配置
    build: {
      // 输出目录
      outDir: 'dist',
      // 静态资源目录
      assetsDir: 'static',
      // 小于此大小的资源转为 base64
      assetsInlineLimit: 4096,
      // 关闭 sourcemap（生产环境）
      sourcemap: false,
      // 压缩
      minify: 'terser',
      // 打包 chunk 大小警告限制
      chunkSizeWarningLimit: 1000,
      // terser 配置（移除 console、debugger）
      terserOptions: {
        compress: {
          drop_console: true,
          drop_debugger: true,
        },
      },
      // 拆包优化
      rollupOptions: {
        output: {
          chunkFileNames: 'static/js/[name]-[hash].js',
          entryFileNames: 'static/js/[name]-[hash].js',
          assetFileNames: 'static/[ext]/[name]-[hash].[ext]',
          manualChunks: {
            vendor: ['vue', 'vue-router', 'pinia'],
          },
        },
      },
    },

// CSS 配置
    css: {
      // 开发时显示源文件
      devSourcemap: true,
      // 预处理器配置（如 scss 全局变量）
      preprocessorOptions: {
        scss: {
          // additionalData: `@import "@/styles/variables.scss";`
        },
      },
    },

// 定义全局常量
    define: {
      __APP_ENV__: JSON.stringify(env.VITE_APP_ENV),
    },
  }
})
```

#### 1.1. 使用说明

1. 直接复制保存为 `vite.config.js`
2. 如果你**不是 Vue 项目**，删掉 `import vue` 和 `plugins: [vue()]`
3. 代理地址、端口、别名可根据自己项目修改
4. 需要全局 scss 变量，打开 `additionalData` 那行注释并修改路径
5. 依赖 `@vitejs/plugin-vue`，Vue 项目需安装：
```bash
npm i @vitejs/plugin-vue -D
```

### 2. 配置 Vite

当从命令行运行 vite 时，Vite 会自动尝试解析项目根目录下名为 vite.config.js 的配置文件（也支持其他 JS 和 TS 扩展名）

可以通过 `--config CLI` 选项显式指定要使用的配置文件（相对于当前工作目录 cwd 解析）：

```bash
vite --config my-config.js
```

### 3. 配置加载

默认情况下，Vite 使用 esbuild 将配置打包到临时文件并加载。这在 monorepo 中导入 TypeScript 文件时可能引发问题。若遇到此类问题，可指定 `--configLoader runner` 改用模块运行器，它不会创建临时配置文件，而是实时转换文件。注意：模块运行器不支持配置文件中的 CJS 语法，但外部 CJS 包可正常使用。

或者，若你使用支持 TypeScript 的环境（例如 node `--experimental-strip-types`），或仅编写纯 JavaScript，可指定 `--configLoader native` 使用环境原生运行时加载配置文件。注意：配置文件导入的模块更新不会被检测，因此不会自动重启 Vite 服务器。

### 4. 配置智能提示

Vite 自带 TypeScript 类型定义，你可借助 JSDoc 类型注释使用 IDE 的智能提示：

```js
/** @type {import('vite').UserConfig} */
export default {
  // ...
}
```

也可使用 defineConfig 辅助函数，无需 JSDoc 注释即可获得智能提示：

```js
import { defineConfig } from 'vite'
export default defineConfig({
  // ...
})
```

Vite 同样支持 TypeScript 配置文件。可在 vite.config.ts 中使用上述 defineConfig 辅助函数，或使用 satisfies 运算符：

```ts
import type { UserConfig } from 'vite'
export default {
  // ...
} satisfies UserConfig
```
> Tips：上面的代码段是放在.ts后缀的文件中

### 5. 条件配置

若配置需根据命令（serve 或 build）、当前模式、是否为 SSR 构建（isSsrBuild）或是否为预览构建（isPreview）来条件判断选项，可导出一个函数：

```js
export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  if (command === 'serve') {
    return {
      // 开发环境专属配置
    }
  } else {
    // command === 'build'
    return {
      // 构建环境专属配置
    }
  }
})
```

> 重要提示：在 Vite API 中，开发时 command 值为 serve（CLI 中 vite、vite dev、vite serve 互为别名），生产构建时为 build（vite build）。

> isSsrBuild 和 isPreview 是额外的可选标识，分别用于区分 build 和 serve 命令的类型。部分加载 Vite 配置的工具可能不支持这些标识，会传入 undefined。因此，建议显式与 true/false 比较。详细介绍点击[《vite 环境构建（isSsrBuild（是否为 SSR 构建）、isPreview（是否为预览构建）》](/admin/Blog/SeeMarkdown?id=1454#isSsrBuild（是否为%20SSR%20构建）)查看

### 6. 配置别名

Vite 配置是放在 vite.config.js 文件中，下面是一个基础配置信息，其中有两个别名的使用`@components`和`@study`

```javascript
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from "path"

// https://vite.dev/config/
export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      "@components":
        path.resolve(__dirname, "src", "components"),
        "@study":
        path.resolve(__dirname, "src", "components", "study")
    }
  }
})
```

配置别名：在上面的这些行中，指示了一个名为 @components 的别名，与项目路径 /src/components 匹配。这样，当导入组件时，我们可以避免编写相对或完整路径，而只需以这种方式引用组件内部的导入：

```javascript
import MyComponent from "@components/MyComponent.vue"
```

### 7. 异步配置

若配置需要调用异步函数，可导出异步函数。该异步函数也可通过 defineConfig 包裹，以获得更好的智能提示支持：

```js
export default defineConfig(async ({ command, mode }) => {
  const data = await asyncFunction()
  return {
    // vite 配置
  }
})
```

### 8. 在配置中使用环境变量

环境变量可照常从 process.env 获取。
注意：Vite 默认不加载 .env 文件，因为需加载的文件只有在解析 Vite 配置后才能确定（例如 root 和 envDir 选项会影响加载行为）。如有需要，可使用导出的 loadEnv 辅助函数加载指定 .env 文件。

```js
import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // 根据当前工作目录中的 `mode` 加载环境变量文件
  // 将第三个参数设为 '' 可加载所有以 `VITE_` 为前缀的环境变量
  const env = loadEnv(mode, process.cwd(), '')
  return {
    // vite 配置
    define: {
      __APP_ENV__: JSON.stringify(env.APP_ENV),
    },
  }
})
```

### 9. 在 VS Code 中调试配置文件

使用默认 --configLoader bundle 行为时，Vite 会将生成的临时配置文件写入 node_modules/.vite-temp 目录，在 Vite 配置文件中设置断点调试时会出现文件未找到错误。要修复此问题，在 .vscode/settings.json 中添加以下配置：

```json
{
  "debug.javascript.terminalOptions": {
    "resolveSourceMapLocations": [
      "${workspaceFolder}/**",
      "!**/node_modules/**",
      "**/node_modules/.vite-temp/**"
    ]
  }
}
```

## Vite 常用查询资料链接

+ [Vite 完整配置参考](https://vitejs.dev/config)
+ [Vite 官方插件](https://vitejs.dev/plugins/)
+ [Vite 社区插件](https://github.com/vitejs/awesome-vite#plugins)