掌握 Vite 环境配置：从 .env 文件到运行模式的完整实践

在基于 vite 搭建的工程中，有时候我们需要抽离，并集中维护一些基于不同运行环境的变量数据，这时候我们往往会定义一些不同的环境变量文件，来集中维护在指定环境下所需的不同数据。

Vite 默认在特殊的 import.meta.env 对象身上暴露了一些常量。这些常量在开发阶段被定义为全局变量，并在构建阶段被静态替换

内置常量（内置常量在所有情况下都可用）：

import.meta.env.MODE: {string} 应用运行模式
import.meta.env.BASE_URL: {string} 部署应用时的基本 URL
import.meta.env.PROD: {boolean} 应用是否运行在生产环境。
import.meta.env.DEV: {boolean} 应用是否运行在开发环境
import.meta.env.SSR: {boolean} 应用是否运行在server上

环境变量：

vite 将定义的环境变量作为字符串暴露在 import.meta.env对象身上。为了防止意外地将一些环境变量泄漏到客户端，只有以 VITE_为前缀的变量才会暴露给经过 vite 处理的代码。例如下面这些环境变量：

typescript 复制代码

VITE_SOME_KEY=123
DB_PASSWORD=foobar

其中只有 VITE_SOME_KEY 会被暴露为 import.meta.env.VITE_SOME_KEY 提供给客户端源码，而 DB_PASSWORD 则不会。

typescript 复制代码

console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined

如果你想要自定义环境变量的前缀：请参考envprefix

注意环境变量解析规则：

如上所示，VITE_SOME_KEY 是一个数字，但在解析时会返回一个字符串。布尔类型的环境变量也会发生同样的情况。在代码中使用时，请确保转换为所需的类型。

环境配置文件

Vite 使用 dotenv 从你的环境目录中的下列文件加载额外的环境变量：

.env ------ 所有情况下都会加载

.env.local ------ 所有情况下都会加载，但会被 git 忽略

.env.[mode] ------ 只在指定模式下加载

.env.[mode].local ------ 只在指定模式下加载，但会被 git 忽略

如果项目工程，需要指定严格且清晰的环境配置数据，往往会在项目根目录下，创建以下配置文件：

文件名	描述
`.env`	全局环境变量文件，在`所有模式下都会加载`，作为基础配置
`.env.local`	`本地环境变量`文件，在`所有模式下都会加载`，会`覆盖 .env 中定义的同名变量`，用于定义`本地敏感数据`，本地需要被 git 忽略
`.development`	`开发模式专用`环境变量，仅在 `development` 模式下加载
`.env.development.local`	`开发模式本地环境`变量，仅在 `development` 模式下加载，用于`定义开发模式下本地的敏感数据`，本地需要被 git 忽略
`.production`	`生产模式专用`环境变量，仅在 `production` 模式`（vite build）`下加载
`.production.local`	`生产模式本地环境`变量，仅在 `production` 模式下加载，用于定义`构建打包时，本地托管的敏感数据`，本地需要被 git 忽略
`.staging`	`预发布/测试模式(自定义模式)`专用环境变量，仅在 `staging` 模式下加载
`.staging.local`	`预发布模式本地环境`变量，仅在 `staging` 模式下加载，用于存放在当前模式下，需要`用到的本地敏感数据`，本地需要被 git 忽略

以上列出的是一个较为完整的多环境变量配置文件，实际配置按需选择。

环境变量加载优先级

一份用于指定模式的文件（例如 .env.production）会比通用文件的优先级更高（例如 .env）。

Vite 总是会加载 .env 和 .env.local 文件，除此之外还会加载模式特定的 .env.[mode] 文件。在模式特定文件中声明的变量优先级高于通用文件中的变量。依据加载顺序，后者依次覆盖前者配置文件中出现的同名变量数据。

但仅在 .env 或 .env.local 中定义的变量仍然可以在环境中使用。

例如：

npm run dev → 加载: .env + .env.local + .env.development + .env.development.local
npm run build → 加载: .env + .env.local + .env.production + .env.production.local
npm run dev:staging → 加载: .env + .env.local + .env.staging + .env.staging.local
npm run build:staging → 加载: .env + .env.local + .env.staging + .env.staging.local

安全注意事项

.env.*.local 文件应是本地的，可以包含敏感变量。你应该将 *.local 添加到你的 .gitignore 中，以避免它们被 git 检入。
由于任何暴露给 Vite 源码的变量最终都将出现在客户端包中，VITE_* 变量应该不包含任何敏感信息。

环境模式

默认情况下，开发服务器 (run dev 命令) 运行在 development (开发) 模式，而 build 命令则运行在 production (生产) 模式。

这意味着当执行 vite build 时，默认它会自动加载 .env.production 以及 .env.production.local 中可能存在的环境变量
或者执行 run dev 时，默认它会自动加载 .env.development 以及 .env.development.local 中可能存在的环境变量

当我们需要自定义一些环境时，如：staging(预发布模式)，可以给命令传递 --mode 选项来覆盖默认模式

例如：

typescript 复制代码

vite build --mode staging   //用来覆盖打包构建时的默认 production 模式

typescript 复制代码

vite --mode staging    //用来覆盖启动本地开发服务器时的默认 development 模式

vue 组件中使用示例：

html 复制代码

<script setup lang="ts">
console.log(import.meta.env);
const name = import.meta.env.VITE_NAME;
const title = import.meta.env.VITE_TITLE;
const home = import.meta.env.VITE_HOME;
const data = import.meta.env.VITE_DATA;
</script>

<template>
  <h1>{{ name }}</h1>
  <h1>{{ title }}</h1>
  <h1>{{ home }}</h1>
  <h1>{{ data }}</h1>
</template>

react 组件中使用示例：

typescript 复制代码

function App() {
	console.log(import.meta.env);
	const name = import.meta.env.VITE_NAME;
	const title = import.meta.env.VITE_TITLE;
	const home = import.meta.env.VITE_HOME;
	const data = import.meta.env.VITE_DATA;
	return (
		<>
			<h1>{name}</h1>
			<h1>{title}</h1>
			<h1>{home}</h1>
			<h1>{data}</h1>
		</>
	);
}
export default App;

如需查看更多有关vite工程的环境变量与运行模式配置访问官方文档

🚵‍♂️ 博主座右铭：向阳而生，我还在路上！

🚴博主想说：将持续性为社区输出自己的资源，同时也见证自己的进步！

🤼‍♂️ 如果都看到这了，博主希望留下你的足迹！【📂收藏！👍点赞！✍️评论！】