Vite 中文文档

vite-config 全面配置(持续更新)


细致全面的 vitejs 配置信息。涵盖了使用 vitejs 开发过程中大部分配置需求。

不建议直接拉取此项目作为模板，希望能按照此教程按需配置，或者复制 vite.config.js 增删配置,并自行安装所需依赖。

vue-cli4 配置见 vue-cli4-config 。

目录

√ 定义全局变量
√ 配置路径别名 alias
√ 配置代理 Proxy
√ 使用 TSX/JSX
√ SFC 支持 name 属性
√ ESlint 错误显示在浏览器中
√ 提供 externals
√ 提供全局 less、scss 变量
√ 按需加载 ElementPlus、Ant Design Vue
√ 生成雪碧图
√ CDN 加载类库
√ 打包分析
√ esbuild error

✅ 定义全局变量


使用 define 定义全局变量

通常情况下，在页面中会用到一些常量，而这些常量可能后期又会发生变更，那么这类常量就不能在代码中使用硬编码处理。

最基础的做法是在构建时生成全局常量，使用时引用全局常量。

vite.config.ts


  1. ``` js
  2. export default defineConfig({
  3.   define: {
  4.     INITIAL_COUNT: 10,
  5.   },
  6. })
  7. ```

在代码中使用：

  1. ``` vue
  2. const count = ref(INITIAL_COUNT);
  3. ```

使用 env 文件定义环境变量

Vite 使用dotenv 可以加载自定义的环境变量。

以下开发的 dev、stage、prod 三种环境为例。将新建四种 env 文件

  1. ``` shell
  2. .env         # 存放不同环境共用的环境变量，定义的变量将被各环境共享
  3. .env.dev     # 开发环境
  4. .env.stage   # 测试环境
  5. .env.prod    # 正式环境
  6. ```

.env


  1. ``` sh
  2. VITE_TOKEN_NAME = 'token'

  4. ```

.env.dev


  1. ``` sh
  2. NODE_ENV = development

  4. VITE_BASE_URL = http://wwww.demo.com/api

  6. VITE_BASE_PATH = /

  8. ```

.env.stage


  1. ``` shell
  2. NODE_ENV = production

  4. VITE_BASE_URL = http://wwww.stage.com/api

  6. VITE_BASE_PATH = /stage
  7. ```

.env.prod


  1. ``` shell
  2. NODE_ENV = production

  4. VITE_BASE_URL = http://wwww.prod.com/api

  6. VITE_BASE_PATH = /prod
  7. ```

vite 的--mode 选项，会读取指定的值匹配的环境变量，如运行 vite --mode dev 时，.env 和.env.dev 两个环境变量文件将被加载。

package.json


  1. ``` json
  2. "scripts": {
  3.   "dev": "vite --mode dev",
  4.   "stage": "vue-tsc --noEmit && vite build --mode stage",
  5.   "prod": "vue-tsc --noEmit && vite build --mode prod",
  6. },
  7. ```

vite.config.ts


  1. ``` ts
  2. import { UserConfig, ConfigEnv, loadEnv } from 'vite'
  3. import vue from '@vitejs/plugin-vue'

  5. export default ({ mode }: ConfigEnv): UserConfig => {
  6.   let plugins = [vue()]

  8.   return {
  9.     plugins,
  10.   }
  11. }
  12. ```

在 vite.config.ts 中可以使用 process.env 上挂载的变量。项目中，Vite 会在一个特殊的 import.meta.env 对象上暴露环境变量。默认以"VITE_"开头的变量，将被挂载在 import.meta.env 对象上。

在 src/env.d.ts 中添加以下信息,可实现环境变量代码自动提示：

  1. ``` ts
  2. interface ImportMetaEnv {
  3.   VITE_BASE_URL: string
  4. }

  6. interface ImportMeta {
  7.   readonly env: ImportMetaEnv
  8. }
  9. ```

▲ 回顶部

✅ 配置路径别名 alias


vite.config.ts


  1. ``` ts
  2. import { UserConfig, ConfigEnv, loadEnv } from 'vite'
  3. import path from 'path'

  5. const nodeResolve = (dir) => path.resolve(__dirname, '.', dir)

  7. export default ({ mode }: ConfigEnv): UserConfig => {
  8.   const resolve = {
  9.     alias: {
  10.       '@': nodeResolve('src'),
  11.       '~': nodeResolve('public'),
  12.     },
  13.   }

  15.   return {
  16.     resolve,
  17.   }
  18. }
  19. ```

使用 typescript 开发，如果出现找不到模块“path”或其相应的类型声明。则需要安装@types/node

  1. ``` shell
  2. npx pnpm i -D @types/node
  3. ```

修改 tsconfig.json 配置：

  1. ``` json
  2. {
  3.   "compilerOptions": {
  4.     "baseUrl": ".",
  5.     "importHelpers": true,
  6.     "skipLibCheck": true,
  7.     "allowSyntheticDefaultImports": true,
  8.     "paths": {
  9.       "@/*": ["src/*"]
  10.     }
  11.   }
  12. }
  13. ```

这样就可以使用'@'来替代相对路径对组件进行引用：

  1. ``` ts
  2. <script lang="ts">import HelloWorld from '@/components/HelloWorld.vue'</script>
  3. ```

也可以使用以下方式配置 alias：

  1. ``` ts
  2. import { UserConfig, ConfigEnv, loadEnv } from 'vite'
  3. import path from 'path'

  5. const nodeResolve = (dir) => path.resolve(__dirname, '.', dir)

  7. export default ({ mode }: ConfigEnv): UserConfig => {
  8.   return {
  9.     resolve: {
  10.       alias: [
  11.         {
  12.           find: /@\//,
  13.           replacement: `${nodeResolve('src')}/`,
  14.         },
  15.         {
  16.           find: /@comps\//,
  17.           replacement: `${nodeResolve('src/components')}/`,
  18.         },
  19.       ],
  20.     },
  21.   }
  22. }
  23. ```

▲ 回顶部

✅ 配置代理 Proxy


Vitejs 的开发服务器选项https://cn.vitejs.dev/config/#server-host

  1. ``` js
  2. export default ({ mode }: ConfigEnv): UserConfig => {
  3.   const server = {
  4.     host: '0.0.0.0',
  5.     port: 3000,
  6.     proxy: {
  7.       '/api': {
  8.         target: 'http://192.168.1.163:8081/',
  9.         changeOrigin: true,
  10.         rewrite: (url) => url.replace(/^\/api/, ''),
  11.       },
  12.     },
  13.   }

  15.   return {
  16.     server,
  17.   }
  18. }
  19. ```

target

实际的后端 api 地址。如请求/api/getUserInfo 会转发到http://192.168.1.163:8081/api/getUserInfo。

changeOrigin

是否改写 origin。设为 true，则请求 header 中 origin 将会与 target 配置项的域名一致。

rewrite

重写转发的请求链接。

▲ 回顶部

✅ 使用 TSX/JSX


@vitejs/plugin-vue-jsx 通过 HMR 提供 Vue 3 JSX 和 TSX 支持。

  1. ``` shell
  2. npx pnpm i @vitejs/plugin-vue-jsx
  3. ```

vite.config.ts


  1. ``` ts
  2. import vueJsx from '@vitejs/plugin-vue-jsx'

  4. export default ({ mode }: ConfigEnv): UserConfig => {
  5.   let plugins = [vueJsx()]

  7.   return {
  8.     plugins,
  9.   }
  10. }
  11. ```

修改 tsconfig.json 配置，使.tsx 中支持 JSX

  1. ``` json
  2. {
  3.   "compilerOptions": {
  4.     "jsx": "preserve" // .tsx中支持JSX
  5.   }
  6. }
  7. ```

▲ 回顶部

✅ SFC 支持 name 属性


vite-plugin-vue-setup-extend 支持<script setup>新增 name 属性

  1. ``` shell
  2. npx pnpm i -D vite-plugin-vue-setup-extend
  3. ```

vite.config.ts


  1. ``` ts
  2. import vueSetupExtend from 'vite-plugin-vue-setup-extend'

  4. export default ({ mode }: ConfigEnv): UserConfig => {
  5.   let plugins = [vueSetupExtend()]

  7.   return {
  8.     plugins,
  9.   }
  10. }
  11. ```

▲ 回顶部

✅ ESlint 错误显示在浏览器中


vite-plugin-eslint

  1. ``` shell
  2. npx pnpm i -D vite-plugin-eslint
  3. ```

vite.config.ts


  1. ``` ts
  2. import { UserConfig, ConfigEnv, loadEnv } from 'vite'
  3. import eslintPlugin from 'vite-plugin-eslint'

  5. export default ({ mode }: ConfigEnv): UserConfig => {
  6.   const IS_PROD = ['prod', 'production'].includes(mode)

  8.   let plugins = []

  10.   if (!IS_PROD) {
  11.     plugins = [
  12.       ...plugins,
  13.       eslintPlugin({
  14.         cache: false,
  15.         include: ['src/**/*.vue', 'src/**/*.ts', 'src/**/*.tsx'],
  16.       }),
  17.     ]
  18.   }

  20.   return {
  21.     plugins,
  22.   }
  23. }
  24. ```

▲ 回顶部

✅ 提供 externals


vite-plugin-externals :为 Vite 提供 commonjs 外部支持

  1. ``` shell
  2. npx pnpm i -D vite-plugin-externals
  3. ```

vite.config.ts


  1. ``` ts
  2. import { UserConfig, ConfigEnv, loadEnv } from 'vite'
  3. import { viteExternalsPlugin } from 'vite-plugin-externals'

  5. export default ({ mode }: ConfigEnv): UserConfig => {
  6.   const IS_PROD = ['prod', 'production'].includes(mode)

  8.   let plugins = []

  10.   if (IS_PROD) {
  11.     plugins = [
  12.       ...plugins,
  13.       viteExternalsPlugin({
  14.         vue: 'Vue',
  15.         react: 'React',
  16.         'react-dom': 'ReactDOM',
  17.         // value support chain, tranform to window['React']['lazy']
  18.         lazy: ['React', 'lazy'],
  19.       }),
  20.     ]
  21.   }

  23.   return {
  24.     plugins,
  25.   }
  26. }
  27. ```

▲ 回顶部

✅ 提供全局 less、scss 变量


提供全局 less 变量

直接提供变量

  1. ``` ts
  2. export default ({ mode }: ConfigEnv): UserConfig => {
  3.   const css = {
  4.     preprocessorOptions: {
  5.       less: {
  6.         additionalData: `@injectedColor: red;`,
  7.         javascriptEnabled: true,
  8.       },
  9.     },
  10.   }
  11.   return {
  12.     css,
  13.   }
  14. }
  15. ```

通过导入 less 文件提供变量

  1. ``` ts
  2. export default ({ mode }: ConfigEnv): UserConfig => {
  3.   const css = {
  4.     preprocessorOptions: {
  5.       less: {
  6.         additionalData: '@import "@/assets/less/variables.less";',
  7.         javascriptEnabled: true,
  8.       },
  9.     },
  10.   }

  12.   return {
  13.     css,
  14.   }
  15. }
  16. ```

提供全局 scss 变量

直接提供变量

  1. ``` ts
  2. export default ({ mode }: ConfigEnv): UserConfig => {
  3.   const css = {
  4.     preprocessorOptions: {
  5.       less: {
  6.         additionalData: `$injectedColor: orange;`,
  7.         javascriptEnabled: true,
  8.       },
  9.     },
  10.   }
  11.   return {
  12.     css,
  13.   }
  14. }
  15. ```

通过导入 scss 文件提供变量

  1. ``` ts
  2. export default ({ mode }: ConfigEnv): UserConfig => {
  3.   const css = {
  4.     preprocessorOptions: {
  5.       scss: {
  6.         additionalData: `@import "@/assets/scss/variables.scss";`,
  7.         javascriptEnabled: true,
  8.       },
  9.     },
  10.   }

  12.   return {
  13.     css,
  14.   }
  15. }
  16. ```

▲ 回顶部

✅ 按需加载 ElementPlus、Ant Design Vue


unplugin-vue-components

按需引入 ElementPlus

unplugin-element-plus 为 Element Plus 按需引入样式。

  1. ``` shell
  2. npx pnpm i -D unplugin-vue-components unplugin-element-plus
  3. ```

vite.config.ts


  1. ``` ts
  2. import { UserConfig, ConfigEnv, loadEnv } from 'vite'

  4. import Components from 'unplugin-vue-components/vite'
  5. import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
  6. import ElementPlus from 'unplugin-element-plus/vite'

  8. export default ({ mode }: ConfigEnv): UserConfig => {
  9.   let plugins = [
  10.     Components({
  11.       resolvers: [ElementPlusResolver()],
  12.     }),
  13.     ElementPlus({}),
  14.   ]

  16.   return {
  17.     plugins,
  18.   }
  19. }
  20. ```

按需引入 Ant Design Vue

  1. ``` shell
  2. npx pnpm i -D unplugin-vue-components
  3. ```

vite.config.ts


  1. ``` ts
  2. import { UserConfig, ConfigEnv, loadEnv } from 'vite'

  4. import Components from 'unplugin-vue-components/vite'
  5. import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'

  7. export default ({ mode }: ConfigEnv): UserConfig => {
  8.   let plugins = [
  9.     Components({
  10.       resolvers: [AntDesignVueResolver()],
  11.     }),
  12.   ]
  13.   return {
  14.     plugins,
  15.   }
  16. }
  17. ```

▲ 回顶部

✅ 生成雪碧图


vite-plugin-svg-icons

  1. ``` shell
  2. npx pnpm i -D vite-plugin-svg-icons
  3. ```

vite.config.ts


  1. ``` ts
  2. import { UserConfig, ConfigEnv, loadEnv } from 'vite'
  3. import viteSvgIcons from 'vite-plugin-svg-icons'

  5. import path from 'path'

  7. const nodeResolve = (dir) => path.resolve(__dirname, dir)

  9. export default ({ mode }: ConfigEnv): UserConfig => {
  10.   let plugins = [
  11.     viteSvgIcons({
  12.       // 指定需要缓存的图标文件夹
  13.       iconDirs: [nodeResolve('icons')],
  14.       // 指定symbolId格式
  15.       symbolId: 'icon-[dir]-[name]',
  16.       // 是否压缩
  17.       svgoOptions: true,
  18.     }),
  19.   ]

  21.   return {
  22.     plugins,
  23.   }
  24. }
  25. ```

使用方式见https://github.com/anncwb/vite-plugin-svg-icons/blob/main/README.zh_CN.md

▲ 回顶部

✅ CDN 加载类库


vite-plugin-cdn-import

  1. ``` shell
  2. npx pnpm i -D vite-plugin-cdn-import
  3. ```

vite.config.ts


  1. ``` ts
  2. import { UserConfig, ConfigEnv, loadEnv } from 'vite'
  3. import importToCDN from 'vite-plugin-cdn-import'

  5. export default ({ mode }: ConfigEnv): UserConfig => {
  6.   const IS_PROD = ['prod', 'production'].includes(mode)

  8.   let plugins = []

  10.   if (IS_PROD) {
  11.     plugins = [
  12.       ...plugins,
  13.       importToCDN({
  14.         modules: [
  15.           {
  16.             name: 'cesium',
  17.             var: 'Cesium',
  18.             path: `https://cesium.com/downloads/cesiumjs/releases/1.88/Build/Cesium/Cesium.js`,
  19.           },
  20.           {
  21.             name: 'widgets',
  22.             path: `https://cesium.com/downloads/cesiumjs/releases/1.88/Build/Cesium/Widgets/widgets.css`,
  23.           },
  24.         ],
  25.       }),
  26.     ]
  27.   }

  29.   return {
  30.     plugins,
  31.   }
  32. }
  33. ```

▲ 回顶部

✅ 打包分析


rollup-plugin-visualizer

  1. ``` shell
  2. npx pnpm i -D rollup-plugin-visualizer
  3. ```

vite.config.ts


  1. ``` ts
  2. import { UserConfig, ConfigEnv, loadEnv } from 'vite'
  3. import { visualizer } from 'rollup-plugin-visualizer'

  5. export default ({ mode }: ConfigEnv): UserConfig => {
  6.   const IS_PROD = ['prod', 'production'].includes(mode)

  8.   let plugins = []

  10.   if (IS_PROD) {
  11.     plugins = [...plugins, visualizer()]
  12.   }

  14.   return {
  15.     plugins,
  16.   }
  17. }
  18. ```

▲ 回顶部

✅ esbuild error


  1. ``` shell
  2. Error: spawn D:\github\vite-config\node_modules\esbuild\esbuild.exe ENOENT
  3.     at Process.ChildProcess._handle.onexit (node:internal/child_process:282:19)
  4.     at onErrorNT (node:internal/child_process:480:16)
  5.     at processTicksAndRejections (node:internal/process/task_queues:83:21)
  6. Emitted 'error' event on ChildProcess instance at:
  7.     at Process.ChildProcess._handle.onexit (node:internal/child_process:288:12)
  8.     at onErrorNT (node:internal/child_process:480:16)
  9.     at processTicksAndRejections (node:internal/process/task_queues:83:21) {
  10. ```

  1. ``` shell
  2. node ./node_modules/esbuild/install.js
  3. ```

▲ 回顶部