认识和使用 Vite 环境变量配置，优化定制化开发体验

news2024/11/25 21:17:30

Vite 官方中文文档：https://cn.vitejs.dev/

环境变量

Vite 内置的环境变量如下：

{
  "MODE": "development",	// 应用的运行环境
  "BASE_URL": "/",	// 部署应用时使用的 URL 前缀
  "PROD": false,	//应用是否正在生产环境中运行
  "DEV": true,	// 与 PROD 相反，表示应用是否在开发环境中运行。
  "SSR": false	//应用是否在服务器端渲染模式
}

.env 文件

Vite 启动时会根据运行环境（即启动命令--mode [mode]），从环境目录（默认为index.html 文件所在的位置）中的下列文件加载额外的环境变量，同时将其中的变量注入到 import.meta.env 对象中：

.env                # 所有情况下都会加载
.env.local          # 所有情况下都会加载，但会被 git 忽略
.env.[mode]         # 只在指定模式下加载
.env.[mode].local   # 只在指定模式下加载，但会被 git 忽略

注：默认情况下.env文件中的变量需要以 VITE_ 为前缀，自定义变量前缀需要特殊配置。

注：加载的环境变量会以字符串形式注入import.meta.env`，在代码中使用时，需要将其转换为所需的类型。

获取环境变量

在业务代码中获取变量

在项目中使用import.meta.env对象获取环境变量：

<script setup lang="ts">
const title = import.meta.env.VITE_PORT
</script>

<template>
  <h1>{{ title }}</h1>
</template>

在 HTML 文件中获取变量

在 HTML 文件中获取环境变量时，可以通过%ENV_NAME%语法获取import.meta.env 中的任何属性：

<title>%VITE_APP_TITLE%</title>

注：如果环境变量在 import.meta.env 中不存在，则会将被忽略而不被替换，这与 JS 中不同，在 JS 中会被替换为 undefined。

在 vite.config.ts 中获取变量

Vite 默认是不加载 .env 文件的，因为这些文件需要在执行完 Vite 配置后才能确定加载哪一个，举个例子，root 和 envDir 选项会影响加载行为。

不过当我们需要在 vite.config.ts 中获取变量时，可以使用 Vite 导出的 loadEnv 函数来加载指定的 .env 文件：

import { defineConfig, loadEnv } from 'vite'

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

自定义变量的前缀

自定义 env 变量的前缀，可以在vite.config.ts文件中配置envPrefix：

import { defineConfig } from 'vite'

// Vite 配置对象
export default defineConfig({
  envPrefix: 'ENV_', // 环境变量前缀
})

这样以 envPrefix 开头的环境变量就会被注入到import.meta.env对象中。

注：当检测到envPrefix被设置为空字符串''时，Vite 将会抛出错误，防止敏感信息的意外泄漏。

当我们想暴露一个不含前缀的变量，可以使用define设置变量：

export default defineConfig({
  define: {
    'import.meta.env.ENV_APP_TITLE': JSON.stringify("My App")
  }
})

指定加载 .env 文件目录

需要指定 Vite 加载.env文件目录时，需要在vite.config.ts文件中设置envDir属性：

export default defineConfig({
  envDir: './env', // 环境变量文件目录，可以是一个绝对路径，也可以是相对于项目根的路径
})

修改 Vite 启动配置

我们可以在vite.config.ts文件中直接修改 Vite 启动配置，只是需要做一些特殊处理：由于 Vite 加载.env文件时其中的环境变量会以字符串形式注入 import.meta.env 对象，所以我们需要对其中的 number、boolean 类型的变量进行类型转换。

例如我们希望在项目启动时，占用端口号从默认的 5173 变为 8080 端口，同时在执行完npm run dev命令后自动弹出浏览器访问页面。

在 .env 文件中添加以下变量：

# 端口号
VITE_PORT = 8080

# 是否自动打开浏览器
VITE_OPEN = true

在vite.config.ts文件中使用loadEnv函数获取当前环境变量，之后将环境变量由字符串类型转为对应类型，最后将配置对象返回：

import { defineConfig, loadEnv } from 'vite' // 引入 Vite 中的 defineConfig 函数
import vue from '@vitejs/plugin-vue' // 引入 Vite 中的 Vue 插件

// Vite 配置对象
export default defineConfig(({ mode }) => {
  // 获取当前环境变量
  const env = loadEnv(mode, process.cwd())

  // 转换环境变量 VITE_PORT 为数字类型
  const port = Number(env.VITE_PORT)
  // 转换环境变量 VITE_OPEN 为布尔类型
  const open = Boolean(env.VITE_OPEN)

  // 配置 Vite 插件
  return {
    plugins: [vue()],
    // 配置开发服务器
    server: {
      port: port,
      open: open,
    }
  }
})