异常教程

vite 环境变量（长文讲解）

更新时间:

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

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

  • 新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;
  • 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

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

在现代前端开发中，vite 环境变量是一个不可或缺的工具，它帮助开发者在不同开发阶段（如开发环境、测试环境、生产环境）中灵活管理配置参数。无论是 API 地址、密钥信息，还是第三方服务的标识符，环境变量都能让代码在不同场景下无缝切换，避免了手动修改配置的繁琐操作。对于编程初学者和中级开发者来说，掌握 Vite 环境变量的使用逻辑，不仅能提升开发效率，还能显著增强项目的可维护性。本文将通过案例与代码示例，深入浅出地解析这一主题，并提供实用技巧帮助读者快速上手。

环境变量的基础概念

什么是环境变量？

环境变量可以被理解为“程序运行时的隐形开关”。它们像是一组预设的参数，允许开发者在不修改代码的情况下，调整程序的行为。例如：

  • 开发环境：API 地址指向本地服务器；
  • 生产环境：API 地址指向线上服务器；
  • 测试环境：使用独立的测试数据库。

通过环境变量，开发者可以避免将敏感信息（如 API 密钥）硬编码到代码中，从而降低安全风险。

环境变量的命名规则

在 Vite 中，环境变量需遵循严格的命名规范：

  • 变量名必须以 VITE_ 开头，例如 VITE_API_URL；
  • 其他前缀（如 NODE_ENV）会被 Vite 自动忽略，除非显式配置。

为什么需要 VITE_ 前缀？
这是为了防止敏感信息泄露。Vite 默认仅暴露以 VITE_ 开头的变量到客户端，而其他变量（如 PRIVATE_SECRET）会被安全地保留在服务端。

Vite 环境变量的配置与使用

创建环境文件

Vite 使用 .env 文件来管理环境变量。在项目根目录下，可以创建以下文件：

.env                # 默认环境变量（所有模式均加载）  
.env.development   # 开发模式（`npm run dev`）  
.env.production    # 生产模式（`npm run build`）  
.env.test          # 测试模式（需手动指定）

比喻说明
可以将这些文件想象为不同场景的“配置包”：开发环境需要快速调试，生产环境需要高性能，测试环境需要模拟数据。通过切换文件，程序能自动适配不同需求。

在代码中引用环境变量

通过 import.meta.env 对象，可以在 JavaScript/TypeScript 中直接访问环境变量：

// 示例：获取 API 地址  
const apiUrl = import.meta.env.VITE_API_URL;  

// 示例：判断当前环境模式  
if (import.meta.env.DEV) {  
  console.log("当前处于开发模式");  
}

注意事项

  1. 变量类型转换：
    环境变量默认是字符串类型。若需使用布尔值或数字，需通过条件判断或类型转换处理：

    const isDebug = import.meta.env.VITE_DEBUG === "true"; // 转为布尔值  
const timeout = parseInt(import.meta.env.VITE_TIMEOUT, 10); // 转为数字

  2. 默认值设置：
    如果某个变量未定义，可以通过逻辑运算符提供默认值：

    const fallbackUrl = import.meta.env.VITE_API_URL || "https://default-api.com";

高级用法：动态环境变量与场景扩展

动态切换环境模式

Vite 允许通过命令行参数动态指定环境模式：

npm run build --mode test

此时，Vite 会优先加载 .env.test 文件中的配置。

结合构建工具与脚本

在 package.json 中，可以通过自定义脚本简化环境切换流程：

{  
  "scripts": {  
    "build-dev": "vite build --mode development",  
    "build-prod": "vite build --mode production",  
    "serve-test": "vite --mode test"  
  }  
}

跨平台注意事项

在 Windows 系统中，环境变量的赋值需使用 = 号，避免 : 或其他符号导致解析错误：

VITE_DB_PORT=3306  

VITE_DB_PORT: 3306

实战案例：构建多环境 API 管理系统

案例背景

假设我们正在开发一个待办事项应用，需要连接后端 API。不同环境的 API 地址如下：
| 环境类型 | API 地址 |
|----------------|-------------------------|
| 开发环境 | http://localhost:3000 |
| 生产环境 | https://api.example.com|
| 测试环境 | https://test.example.com|

实现步骤

  1. 创建环境文件：
    在项目根目录下创建 .env.development、.env.production、.env.test：

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

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

# .env.test  
VITE_API_URL=https://test.example.com

  2. 编写 API 请求函数：
    在代码中通过环境变量动态获取 API 地址：

    // src/api.js  
export const fetchTodos = async () => {  
  const response = await fetch(import.meta.env.VITE_API_URL + "/todos");  
  return response.json();  
};

  3. 测试不同模式：

    • 开发模式：直接运行 npm run dev，请求会指向本地服务器；
    • 测试模式：执行 npm run build --mode test，构建时使用测试环境的 API 地址。

扩展场景：动态注入变量

若需在构建时动态注入变量（如 CI/CD 环境中的密钥），可以通过命令行参数覆盖：

npm run build --define 'process.env.VITE_API_KEY=your-secret-key'

常见问题与解决方案

问题 1：环境变量未生效

可能原因：

  • 变量名未以 VITE_ 开头；
  • 文件命名错误（如 .env.develop 而非 .env.development）；
  • 缓存问题（Vite 可能缓存旧配置）。

解决方法：

  1. 检查变量名是否符合规范；
  2. 重启开发服务器或执行 npm run build --force 强制重新构建；
  3. 使用 VITE_ 前缀重命名变量。

问题 2：敏感信息泄露风险

解决方案：

  • 避免将敏感变量（如数据库密码）直接写入 .env 文件；
  • 使用环境变量管理工具（如 Docker Secrets 或 AWS Parameter Store）；
  • 在 .gitignore 中添加 .env 文件，防止其被提交到版本控制中。

结论

vite 环境变量是现代前端项目中高效管理配置的核心工具。通过本文的讲解与案例，读者可以掌握环境变量的基本用法、进阶技巧以及常见问题的解决方案。无论是切换开发模式、管理 API 端点，还是应对复杂的部署场景，环境变量都能帮助开发者实现代码与配置的解耦，提升开发流程的灵活性与安全性。

希望本文能成为你技术成长路上的参考指南。如果在实际应用中遇到问题，欢迎进一步探讨！

最新发布

查看更多文章