Vite配置实战

文章目录

前言
[一、配置文件与 defineConfig](#一、配置文件与 defineConfig)
- [1.1 `vite.config.ts` 是入口](#1.1 vite.config.ts 是入口)
- [1.2 为什么推荐 `defineConfig`](#1.2 为什么推荐 defineConfig)
- [1.3 配置可以按 mode 区分](#1.3 配置可以按 mode 区分)
二、路径别名：resolve.alias
- [2.1 为什么要配别名](#2.1 为什么要配别名)
- [2.2 Vite 里的写法](#2.2 Vite 里的写法)
- [2.3 记得和 tsconfig 对齐](#2.3 记得和 tsconfig 对齐)
三、开发代理：server.proxy
- [3.1 代理主要解决什么问题](#3.1 代理主要解决什么问题)
- [3.2 标准 proxy 配置](#3.2 标准 proxy 配置)
- [3.3 需要重写路径时怎么配](#3.3 需要重写路径时怎么配)
- [3.4 一个更实战的写法](#3.4 一个更实战的写法)
[四、环境变量：.env 与 import.meta.env](#四、环境变量：.env 与 import.meta.env)
- [4.1 常见文件](#4.1 常见文件)
- [4.2 变量为什么必须以 `VITE_` 开头](#4.2 变量为什么必须以 VITE_ 开头)
- [4.3 `import.meta.env` 和 `process.env` 的区别](#4.3 import.meta.env 和 process.env 的区别)
- [4.4 在配置文件里读取 env](#4.4 在配置文件里读取 env)
[五、`base` 公共路径怎么配](#五、base 公共路径怎么配)
- [5.1 `base` 解决什么问题](#5.1 base 解决什么问题)
- [5.2 子目录部署示例](#5.2 子目录部署示例)
- [5.3 CDN 或多环境场景](#5.3 CDN 或多环境场景)
[六、CSS 相关配置](#六、CSS 相关配置)
- [6.1 预处理器](#6.1 预处理器)
- [6.2 CSS Modules](#6.2 CSS Modules)
- [6.3 PostCSS](#6.3 PostCSS)
[七、Vue 项目里的常见插件配置](#七、Vue 项目里的常见插件配置)
- [7.1 `@vitejs/plugin-vue`](#7.1 @vitejs/plugin-vue)
- [7.2 JSX 支持](#7.2 JSX 支持)
- [7.3 一个常见的完整配置](#7.3 一个常见的完整配置)
八、配置时最常见的坑
- [8.1 别名只配了一边](#8.1 别名只配了一边)
- [8.2 环境变量写了但代码里读不到](#8.2 环境变量写了但代码里读不到)
- [8.3 代理生效了，但路径不对](#8.3 代理生效了，但路径不对)
- [8.4 部署后静态资源 404](#8.4 部署后静态资源 404)
- [8.5 `process.env` 习惯性误用](#8.5 process.env 习惯性误用)
九、面试聚焦
- [9.1 `import.meta.env` 和 `process.env` 区别是什么？](#9.1 import.meta.env 和 process.env 区别是什么？)
- [9.2 为什么环境变量必须以 `VITE_` 开头？](#9.2 为什么环境变量必须以 VITE_ 开头？)
- [9.3 本地连后端 API，最标准的 proxy 配置怎么写？](#9.3 本地连后端 API，最标准的 proxy 配置怎么写？)
十、易混淆点
十一、思考与练习
总结

前言

理解了 Vite 为什么快，只算完成了"原理入门"；真正进项目后，更常见的问题其实是：别名怎么配、代理怎么写、环境变量为什么读不到、部署到子目录为什么静态资源 404。

本篇聚焦 Vite 在项目里的高频配置实战，讲清楚：

vite.config.ts 应该怎么组织
别名、代理、环境变量、base 分别解决什么问题
Vue 项目里常见的 CSS 与插件配置怎么写

一、配置文件与 defineConfig

1.1 `vite.config.ts` 是入口

Vite 的核心配置文件通常就是项目根目录下的 vite.config.ts。

最小配置一般长这样：

typescript 复制代码

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

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

如果你用的是 React，就换成对应插件；如果是 Vue 项目，@vitejs/plugin-vue 基本是默认配置。

1.2 为什么推荐 `defineConfig`

typescript 复制代码

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    port: 5173
  }
})

defineConfig 的好处主要有两个：

提供更完整的类型提示
写 TS 配置时更容易拿到字段自动补全

它不是必须，但在 vite.config.ts 里几乎总是推荐使用。

1.3 配置可以按 mode 区分

typescript 复制代码

import { defineConfig } from 'vite'

export default defineConfig(({ mode }) => {
  return {
    server: {
      port: mode === 'development' ? 5173 : 8080
    }
  }
})

当你需要根据开发、测试、生产环境切换配置时，可以把 defineConfig 写成函数形式，直接拿到 mode。

二、路径别名：resolve.alias

2.1 为什么要配别名

如果项目层级一深，就会出现这种导入：

typescript 复制代码

import UserCard from '../../../../components/UserCard.vue'

这种路径有两个问题：

可读性差
文件移动后容易大面积失效

所以项目里通常会统一配置 @ 指向 src。

2.2 Vite 里的写法

typescript 复制代码

// vite.config.ts
import path from 'node:path'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
})

然后组件里就可以这样写：

typescript 复制代码

import UserCard from '@/components/UserCard.vue'

2.3 记得和 tsconfig 对齐

很多人只配了 Vite，结果运行没问题，TS 却报路径错误，原因就是 tsconfig.json 没同步。

json 复制代码

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

要记住：

vite.config.ts 负责运行时解析
tsconfig.json 负责 TypeScript 和 IDE 识别

两边都要配。

三、开发代理：server.proxy

3.1 代理主要解决什么问题

本地前端常常跑在：

http://localhost:5173

后端接口跑在：

http://localhost:8080

这时候浏览器会遇到跨域问题。开发阶段最常见的处理方式，就是通过 Vite dev server 做代理。

3.2 标准 proxy 配置

typescript 复制代码

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true
      }
    }
  }
})

前端这样请求：

typescript 复制代码

fetch('/api/users')

实际会被代理到：

text 复制代码

http://localhost:8080/api/users

3.3 需要重写路径时怎么配

如果后端真实接口没有 /api 前缀，而你希望前端统一写 /api，就可以加 rewrite：

typescript 复制代码

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '')
    }
  }
}

这样：

前端请求：/api/users
实际转发：http://localhost:8080/users

3.4 一个更实战的写法

typescript 复制代码

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

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')

  return {
    plugins: [vue()],
    server: {
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL,
          changeOrigin: true
        }
      }
    }
  }
})

这样本地、测试环境只需要换 .env 文件，不用手改配置。

四、环境变量：.env 与 import.meta.env

4.1 常见文件

Vite 常见的环境变量文件包括：

.env
.env.local
.env.development
.env.production
.env.development.local

通常可以这样理解：

.env：所有环境共享
.env.development：开发环境专用
.env.production：生产环境专用
.local：本地私有，不建议提交仓库

4.2 变量为什么必须以 `VITE_` 开头

env 复制代码

VITE_APP_TITLE=Vite Demo
VITE_API_BASE_URL=http://localhost:8080

在客户端代码里：

typescript 复制代码

console.log(import.meta.env.VITE_APP_TITLE)
console.log(import.meta.env.VITE_API_BASE_URL)

Vite 规定，只有以 VITE_ 开头的变量，才会暴露给前端代码。这样做是为了避免把敏感环境变量意外打进浏览器包里。

4.3 `import.meta.env` 和 `process.env` 的区别

在 Vite 项目里，前端代码应该优先使用：

typescript 复制代码

import.meta.env

而不是：

typescript 复制代码

process.env

因为：

process.env 更像 Node / 旧构建工具语境
Vite 的客户端环境变量入口是 import.meta.env

常见字段还有：

typescript 复制代码

console.log(import.meta.env.MODE)
console.log(import.meta.env.DEV)
console.log(import.meta.env.PROD)
console.log(import.meta.env.BASE_URL)

4.4 在配置文件里读取 env

如果是在 vite.config.ts 里使用环境变量，不是直接用 import.meta.env，而是用 loadEnv：

typescript 复制代码

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')

  return {
    server: {
      port: Number(env.VITE_PORT || 5173)
    }
  }
})

这里第三个参数写空字符串 ''，表示把所有变量都读进来；如果只想读 VITE_ 前缀，也可以按默认方式处理。

五、`base` 公共路径怎么配

5.1 `base` 解决什么问题

如果项目不是部署在域名根路径，而是部署在子目录，比如：

text 复制代码

https://example.com/admin/

这时静态资源路径如果还是默认根路径，就可能出现 404。

5.2 子目录部署示例

typescript 复制代码

import { defineConfig } from 'vite'

export default defineConfig({
  base: '/admin/'
})

构建后资源引用会带上 /admin/ 前缀，更适合部署到子路径。

5.3 CDN 或多环境场景

typescript 复制代码

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')

  return {
    base: env.VITE_PUBLIC_PATH || '/'
  }
})

这样测试、预发布、线上可以走不同的资源前缀。

六、CSS 相关配置

6.1 预处理器

如果项目使用 SCSS、Less，可以直接配置预处理器选项：

typescript 复制代码

import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "@/styles/variables.scss" as *;`
      }
    }
  }
})

这个配置很适合做全局变量、mixin 注入，避免每个文件都手动 @use 一次。

6.2 CSS Modules

typescript 复制代码

import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    modules: {
      localsConvention: 'camelCaseOnly'
    }
  }
})

这样类名导出会更适合 JS/TS 使用。

6.3 PostCSS

Vite 默认支持 PostCSS，如果项目根目录有 postcss.config.js，会自动读取。

例如：

javascript 复制代码

// postcss.config.js
module.exports = {
  plugins: {
    autoprefixer: {}
  }
}

所以很多时候你不需要在 vite.config.ts 里重复写一遍。

七、Vue 项目里的常见插件配置

7.1 `@vitejs/plugin-vue`

Vue 项目最基础的就是这个插件：

typescript 复制代码

import vue from '@vitejs/plugin-vue'

plugins: [vue()]

它负责让 Vite 正确处理：

.vue 单文件组件
模板编译
SFC 的 HMR

7.2 JSX 支持

如果你在 Vue 里要写 JSX / TSX，可以加：

typescript 复制代码

import vueJsx from '@vitejs/plugin-vue-jsx'

plugins: [vue(), vueJsx()]

不是所有 Vue 项目都需要，但组件库、函数式渲染场景会比较常见。

7.3 一个常见的完整配置

typescript 复制代码

// vite.config.ts
import path from 'node:path'
import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')

  return {
    plugins: [vue()],
    base: env.VITE_PUBLIC_PATH || '/',
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src')
      }
    },
    server: {
      host: '0.0.0.0',
      port: Number(env.VITE_PORT || 5173),
      open: true,
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL,
          changeOrigin: true
        }
      }
    },
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@use "@/styles/variables.scss" as *;`
        }
      }
    }
  }
})

这个版本已经覆盖了绝大部分中后台项目的常见开发需求。

八、配置时最常见的坑

8.1 别名只配了一边

如果你只在 vite.config.ts 配了 alias，但没在 tsconfig.json 配 paths，结果通常是：

浏览器里能跑
IDE 或 tsc 报路径找不到

8.2 环境变量写了但代码里读不到

高频原因有三个：

没有以 VITE_ 开头
改完 .env 后没重启 dev server
在 vite.config.ts 里误用了 import.meta.env

8.3 代理生效了，但路径不对

如果后端接口没有 /api 前缀，就要确认是否需要 rewrite。很多"接口 404"不是代理没生效，而是转发后的真实路径不对。

8.4 部署后静态资源 404

优先检查：

base 是否正确
部署路径是不是根路径
Nginx 静态目录与资源前缀是否一致

8.5 `process.env` 习惯性误用

从 Vue CLI、Webpack 项目迁到 Vite 时，最常见的旧习惯就是继续写：

typescript 复制代码

process.env.NODE_ENV

在 Vite 里应该尽量改为：

typescript 复制代码

import.meta.env.MODE
import.meta.env.PROD
import.meta.env.DEV

九、面试聚焦

9.1 `import.meta.env` 和 `process.env` 区别是什么？

在 Vite 客户端代码里，环境变量入口是 import.meta.env；process.env 更偏 Node 或传统打包工具语境。迁移项目时要特别注意这一点。

9.2 为什么环境变量必须以 `VITE_` 开头？

因为 Vite 只会把约定前缀的变量暴露给前端代码，避免把敏感变量无意中注入到浏览器端。

9.3 本地连后端 API，最标准的 proxy 配置怎么写？

核心就是：

server.proxy
target
changeOrigin
必要时加 rewrite

本质是让浏览器始终请求同源 dev server，再由 Vite 转发到真实后端。

十、易混淆点

alias 和 paths 不是二选一：一个给 Vite，一个给 TS/IDE，通常要一起配。
import.meta.env 不能直接在配置文件里替代 loadEnv：配置阶段和客户端运行阶段不是同一套上下文。
proxy 只解决开发阶段联调问题：线上跨域仍要靠后端、网关或 Nginx 方案处理。
base 影响的是构建产物路径：本地开发看不出问题，部署后才容易暴露。
.env.local 适合放本地私有配置：不要把敏感地址、密钥直接提交仓库。

十一、思考与练习

1. 为什么配置 @ 别名时，vite.config.ts 和 tsconfig.json 都要改？

解析：前者负责运行时模块解析，后者负责 TS 与 IDE 的静态识别；只改一边会出现"能跑但报错"或"有提示但跑不通"的问题。

2. 什么时候需要给 proxy 加 rewrite？

解析：当前端请求前缀和后端真实接口前缀不一致时，就需要重写路径。

3. 为什么 .env 改完后有时页面读不到新值？

解析：Vite 启动后会读取环境变量，修改 .env 后通常需要重启 dev server。

4. 项目部署到 /admin/ 子目录后资源 404，第一反应查什么？

解析：先查 base，再看服务器静态资源映射与路由配置。

5. 为什么说 server.proxy 不是线上跨域方案？

解析：它本质是开发服务器转发能力，只在本地开发或预览链路中生效，生产环境仍需依赖真实服务端代理或网关配置。

总结

配置入口 ：用 vite.config.ts + defineConfig 组织项目配置
高频配置 ：别名、代理、环境变量、base 是最常见的四类需求
Vue 项目常配 ：@vitejs/plugin-vue、SCSS 全局注入、必要时加 JSX 支持
常见误区 ：alias 不同步、误用 process.env、忘记重启、子目录部署不配 base
实战原则 ：配置尽量参数化，用 mode 与 loadEnv 做多环境切换，避免手改常量

文章目录

前言

一、配置文件与 defineConfig

1.1 vite.config.ts 是入口

1.2 为什么推荐 defineConfig

1.3 配置可以按 mode 区分

二、路径别名：resolve.alias

2.1 为什么要配别名

2.2 Vite 里的写法

2.3 记得和 tsconfig 对齐

三、开发代理：server.proxy

3.1 代理主要解决什么问题

3.2 标准 proxy 配置

3.3 需要重写路径时怎么配

3.4 一个更实战的写法

四、环境变量：.env 与 import.meta.env

4.1 常见文件

4.2 变量为什么必须以 VITE_ 开头

4.3 import.meta.env 和 process.env 的区别

4.4 在配置文件里读取 env

五、base 公共路径怎么配

5.1 base 解决什么问题

5.2 子目录部署示例

5.3 CDN 或多环境场景

六、CSS 相关配置

6.1 预处理器

6.2 CSS Modules

6.3 PostCSS

七、Vue 项目里的常见插件配置

7.1 @vitejs/plugin-vue

7.2 JSX 支持

7.3 一个常见的完整配置

八、配置时最常见的坑

8.1 别名只配了一边

8.2 环境变量写了但代码里读不到

8.3 代理生效了，但路径不对

8.4 部署后静态资源 404

8.5 process.env 习惯性误用

九、面试聚焦

9.1 import.meta.env 和 process.env 区别是什么？

9.2 为什么环境变量必须以 VITE_ 开头？

9.3 本地连后端 API，最标准的 proxy 配置怎么写？

十、易混淆点

十一、思考与练习

总结

1.1 `vite.config.ts` 是入口

1.2 为什么推荐 `defineConfig`

4.2 变量为什么必须以 `VITE_` 开头

4.3 `import.meta.env` 和 `process.env` 的区别

五、`base` 公共路径怎么配

5.1 `base` 解决什么问题

7.1 `@vitejs/plugin-vue`

8.5 `process.env` 习惯性误用

9.1 `import.meta.env` 和 `process.env` 区别是什么？

9.2 为什么环境变量必须以 `VITE_` 开头？