Vite 环境变量配置与类型处理本文介绍 Vite 环境变量的配置方法，包括定义、类型声明、环境变量处理逻辑，以及在 V

一、环境变量

Vite 支持 .env 文件定义环境变量，需以 VITE_ 开头才能在客户端访问：

# 自定义环境变量（必须以 VITE_ 开头）

# 应用标题
VITE_APP_TITLE='Vite App'

# 打包输出目录
VITE_OUTPUT_DIR='dist'

# 资源基础路径
VITE_PUBLIC_PATH='/'

# API 接口地址
VITE_BASE_API='/api'

# 接口代理地址
VITE_BASE_URL='https://example.com'

# 超时时间（毫秒）
VITE_REQUEST_TIMEOUT='10000'

# 是否移除 console
VITE_DROP_CONSOLE='true'

# 是否自动打开浏览器
VITE_AUTO_OPEN='false'

📌 更多环境变量设置请查看 Vite 官方文档

二、TypeScript 类型声明

为保证环境变量的类型安全，可在 types/vite-env.d.ts 中声明：

/** 原生读取出的环境变量类型 */
interface ImportMetaEnv {
  /** 应用默认标题 */
  VITE_APP_TITLE: string
  /** 后端接口公共路径 */
  VITE_BASE_API: string
  /** 后端接口代理地址 */
  VITE_BASE_URL: string
  /** 指定打包文件的输出目录 */
  VITE_OUTPUT_DIR: string
  /** 部署应用包时的基本 URL */
  VITE_PUBLIC_PATH: string
  /** 路由模式 */
  VITE_ROUTER_MODE: 'hash' | 'history'

  /** 开发服务器的监听端口 */
  VITE_DROP_CONSOLE: string
  /** 打包后移除所有的 console、debugger */
  VITE_SERVER_PORT: string
  /** 请求超时时间 单位秒 */
  VITE_REQUEST_TIMEOUT: string
  /** 是否自动打开浏览器 */
  VITE_AUTO_OPEN: string
  /** 是否开启路由加载时的顶部进度条 */
  VITE_ROUTER_NPROGRESS: string
  /** 是否开启请求接口时的顶部进度条 */
  VITE_REQUEST_NPROGRESS: string
  /** 打包后是否移除所有的注释 */
  VITE_CLEAR_COMMENT: string
}

/** 原生读取出的环境变量经过处理后的类型 */
interface ViteEnv extends Omit<ImportMetaEnv, 'BASE_URL'> {
  /** 当前运行模式 */
  MODE: string
  /** 是否为开发环境 */
  DEV: boolean
  /** 是否为生产环境 */
  PROD: boolean
  /** 开发服务器的监听端口 */
  VITE_SERVER_PORT: number
  /** 请求超时时间 单位秒 */
  VITE_REQUEST_TIMEOUT: number
  /** 是否自动打开浏览器 */
  VITE_AUTO_OPEN: boolean
  /** 打包后移除所有的 console、debugger */
  VITE_DROP_CONSOLE: boolean
  /** 是否开启路由加载时的顶部进度条 */
  VITE_ROUTER_NPROGRESS: boolean
  /** 是否开启请求接口时的顶部进度条 */
  VITE_REQUEST_NPROGRESS: boolean
  /** 打包后是否移除所有的注释 */
  VITE_CLEAR_COMMENT: boolean
}

/** 让 Vite 识别 env 类型 */
interface ImportMeta {
  /** 利用 Readonly 泛型工具类全部修改为只读属性 */
  readonly env: Readonly<ImportMetaEnv>
}

/** 处理后的环境变量（全局可用） */
/** 原生读取出的环境变量经过处理后的类型 src 下任意位置可用此访问 类比 __dirname 使用 */
declare const __RUNTIME_CONFIG__: ViteEnv

三、环境变量处理

3.1 处理 `.env` 变量

在 vite.config.ts 处理 .env 变量，转换为正确的类型：

import { defineConfig, loadEnv } from 'vite'

/** 处理环境变量 */
function warpperEnv(envConfing: Recordable<string>, mode: string): ViteEnv {
  const runtimeConfig = {} as ViteEnv
  runtimeConfig.MODE = mode
  runtimeConfig.DEV = mode === 'development'
  runtimeConfig.PROD = mode === 'production'
  for (const [key, value] of Object.entries(envConfing)) {
    // 默认先给原值 其后看情况处理
    runtimeConfig[key] = value
    // 布尔值
    if (typeof value === 'string' && ['true', 'false'].includes(value)) {
      runtimeConfig[key] = value === 'true' ? true : false
    }
    // 数值
    if (typeof value === 'string' && !Number.isNaN(Number(value))) {
      runtimeConfig[key] = +value // 数值类型处理
    }
  }
  return runtimeConfig
}

export default defineConfig(({ mode }) => {
  // 根据当前工作目录中的 `mode` 加载 .env 文件
  // 设置第三个参数为 '' 来加载所有环境变量，而不管是否有 `VITE_` 前缀
  const runtimeConfig = warpperEnv(loadEnv(mode, root, 'VITE_'), mode) // 对原生环境变量进行二次处理
  
  return {
    define: {
      /** 将处理后的环境变量定义为全局常量 */
      __RUNTIME_CONFIG__: runtimeConfig,
    },
    
    // 部署应用包时的基本 URL
    base: runtimeConfig.VITE_PUBLIC_PATH,
    
    esbuild: {
      // 打包后是否移除所有的 console、debugger
      drop: runtimeConfig.VITE_DROP_CONSOLE ? ['console', 'debugger'] : [],
      // 打包后是否移除所有的注释
      legalComments: runtimeConfig.VITE_CLEAR_COMMENT ? 'none' : 'inline',
    }
  }
})

3.2 在 Vue 组件中使用环境变量

在 src/views/Dashboard/index.vue 组件中：

<script setup lang="ts">
defineOptions({ name: 'Dashboard' })

// 直接访问全局环境变量
const VITE_APP_TITLE = __RUNTIME_CONFIG__.VITE_APP_TITLE
console.log('应用标题:', VITE_APP_TITLE) // Vite App
</script>

3.3 在 TypeScript 代码中使用环境变量

在 src/utils/request.ts 配置 Axios：

import axios from 'axios'

const request = axios.create({
  // API 基础路径
  baseURL: __RUNTIME_CONFIG__.VITE_BASE_API,
  // 超时时间（转换为毫秒）
  timeout: __RUNTIME_CONFIG__.VITE_REQUEST_TIMEOUT * 1000,
})

export default request

四、总结

✅ .env 变量必须以 VITE_ 开头才能在客户端访问
✅ 通过 vite.config.ts 处理环境变量，转换为正确类型
✅ 在 Web 端使用 __RUNTIME_CONFIG__ 访问全局环境变量

这样配置可以提升环境变量的可维护性，同时提高代码的可读性和安全性。🚀

Vite 环境变量配置与类型处理