异常教程

vite .env（超详细）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

在现代前端开发中，Vite 作为新一代构建工具，凭借其闪电般的启动速度和灵活的配置方式，迅速成为开发者首选的项目构建方案。然而，随着项目复杂度的提升，如何安全、高效地管理不同环境下的配置参数（如 API 地址、密钥等），成为开发者必须面对的挑战。
Vite .env 文件正是为此而生的解决方案。它允许开发者通过环境变量的方式，将敏感信息与业务逻辑分离，并在不同环境中动态切换配置。本文将从基础概念到实战案例，手把手带你掌握 Vite .env 的核心原理与最佳实践，帮助你构建更健壮、更安全的前端项目。

环境变量的基本概念：为什么需要它？

比喻：快递分拣中心的“地址标签”

想象一个快递分拣中心，每个包裹上都贴有不同的地址标签。这些标签决定了包裹最终会被送到哪个城市、哪个收件人手中。环境变量的作用与此类似：它为不同环境（如开发环境、测试环境、生产环境）提供“地址标签”，确保代码在不同场景下访问正确的资源。

环境变量的三大核心价值

  1. 安全隔离：避免将敏感信息（如数据库密码、API 密钥）直接写入代码库。
  2. 灵活切换：一键切换不同环境的配置（如开发环境使用本地 API，生产环境使用线上服务）。
  3. 降低耦合度：业务代码无需关心具体环境细节，只需通过变量名调用配置。

Vite 中的 .env 文件：从零开始配置

基础规则与命名规范

在 Vite 项目中，环境变量通过以 .env 结尾的文件进行管理。关键规则如下：

  • 文件名规则：

    • .env：默认加载的基础配置。
    • .env.local：本地开发专用配置（不会被提交到版本控制）。
    • .env.[mode].local：如 .env.development.local，特定模式下的本地配置。
    • .env.[mode]：如 .env.production，特定模式下的公共配置。

  • 变量命名规则：

    • 必须以 VITE_ 前缀开头（如 VITE_API_URL）。
    • 大写字母与下划线组合（如 VITE_DEBUG_MODE）。

为什么需要 VITE_ 前缀？
因为 Vite 默认仅暴露以 VITE_ 开头的变量到客户端，其他变量仅在服务端可见，这是为了增强安全性。

第一个 .env 文件实战

步骤 1：创建基础配置文件

在项目根目录新建 .env.development 文件，内容如下：

VITE_API_URL=http://localhost:3000/api  
VITE_DEBUG=true

步骤 2：在代码中引用变量

在 Vue 组件或 React 组件中，可通过 import.meta.env 访问变量：

// Vue 3 组件示例  
<script setup>  
const apiUrl = import.meta.env.VITE_API_URL  
const debugMode = import.meta.env.VITE_DEBUG === 'true' ? true : false  
</script>  

// React 组件示例  
import { useEffect } from 'react'  

useEffect(() => {  
  const apiUrl = process.env.VITE_API_URL  
  console.log('当前 API 地址:', apiUrl)  
}, [])

步骤 3：验证配置是否生效

启动开发服务器后，检查控制台输出是否显示 http://localhost:3000/api，确认变量已正确加载。

进阶用法：动态生成与高级场景

案例 1：多环境 API 地址的动态切换

假设你的项目需要根据环境自动切换 API 端点：

// .env.development  
VITE_API_URL=http://localhost:3000/api  

// .env.production  
VITE_API_URL=https://api.example.com/production

在代码中无需任何改动，Vite 会根据运行模式（npm run dev 或 npm run build）自动加载对应的变量。

案例 2：通过 CLI 参数动态覆盖配置

Vite 允许通过命令行参数临时覆盖环境变量：

npm run dev -- --env.VITE_API_URL=https://staging.example.com/api

此命令会在开发模式下临时使用 staging 环境的 API 地址，无需修改文件。

案例 3：结合第三方工具生成 .env 文件

在大型项目中，可通过工具（如 dotenv-cli）动态生成 .env 文件：

  1. 安装依赖： 
    npm install dotenv-cli --save-dev
  2. 在 vite.config.js 中配置： 
    import { defineConfig } from 'vite'  
import * as dotenv from 'dotenv'  

export default defineConfig(({ mode }) => {  
  const env = dotenv.config({ path: `.env.${mode}` }).parsed  
  return {  
    define: {  
      __APP_ENV__: JSON.stringify(env)  
    }  
  }  
})

此方法可将环境变量注入到构建过程中，适用于更复杂的场景。

常见问题与解决方案

问题 1：环境变量未加载

可能原因：

  • 变量名未以 VITE_ 开头。
  • 文件名拼写错误（如 .env.develop 误写为 .env.development）。

解决方案：
检查文件名和变量命名，确保符合 Vite 的命名规范。

问题 2：生产环境变量泄露

风险场景：
若将未做前缀的变量（如 API_KEY=123）写入 .env 文件，Vite 会将其暴露到客户端，导致敏感信息泄露。

解决方案：

  • 严格使用 VITE_ 前缀。
  • 敏感信息建议通过后端接口动态获取，而非硬编码。

问题 3：多环境配置冲突

场景：
.env 和 .env.development 中同时定义 VITE_API_URL，导致优先级混乱。

优先级规则：
Vite 的加载顺序遵循：
命令行参数 > .env.local > .env.[mode].local > .env.[mode] > .env

实战案例：前后端分离项目的环境变量管理

场景描述

假设你正在开发一个电商网站，需要对接后端服务。开发环境使用本地 API，生产环境使用线上服务，测试环境则需要访问 QA 环境的接口。

配置步骤

  1. 创建三个环境文件：

    // .env.development  
VITE_API_URL=http://localhost:3000  

// .env.production  
VITE_API_URL=https://api.example.com  

// .env.test  
VITE_API_URL=https://api.qa.example.com

  2. 在代码中统一调用变量：

    const fetchProducts = async () => {  
  const response = await fetch(`${import.meta.env.VITE_API_URL}/products`)  
  return response.json()  
}

  3. 通过命令切换环境：

    # 开发模式  
npm run dev  

# 测试模式  
npm run build --mode test  

# 生产模式  
npm run build --mode production

结论

通过本文的讲解，你已经掌握了 Vite .env 文件的核心原理与实战技巧。环境变量不仅简化了多环境配置的管理，还显著提升了代码的安全性和可维护性。

下一步行动建议：

  1. 在你的 Vite 项目中实践本文提到的配置方法。
  2. 尝试结合工具（如 dotenv）实现更复杂的环境变量管理。
  3. 阅读 Vite 官方文档的环境变量章节，深入理解其底层机制。

记住，环境变量的设计如同一座桥梁——它连接着代码与真实世界的数据，合理使用它，你的项目将更加灵活、安全且易于扩展。

最新发布

查看更多文章