bg
返回博客

前端工程化中的环境变量

前端工程化中的环境变量，如何正确使用？

5minzh-CNCIENVFRONTEND

在前端工程化的过程中，我们经常会接触到 环境变量（Environment Variables）。无论是使用 Vite、Webpack，还是 Next.js、Nuxt 等框架，环境变量都是一个不可或缺的概念。它们看似只是一些字符串配置，但在项目的可维护性、可移植性和安全性上都起着重要作用。本文将从以下几个角度展开：

  1. 什么是环境变量，为什么要有环境变量
  2. 环境变量可以是什么
  3. 环境变量的加载顺序

1. 什么是环境变量，为什么要有环境变量

环境变量 本质上就是一组 键值对，用来描述某个运行环境下的配置信息。 在前端项目中，我们通常会根据运行环境（开发、测试、生产）来调整一些配置，比如：

  • API 请求的基础地址
  • 是否启用调试模式
  • 第三方 SDK 的密钥
  • 日志打印级别

如果没有环境变量，我们可能需要在代码中硬编码这些值：

TEXT
const API_BASE_URL = "http://localhost:3000"; // 开发环境
// const API_BASE_URL = "https://api.example.com"; // 生产环境

这种方式的问题是：

  • 不灵活：每次切换环境都要手动改代码。
  • 容易出错：一旦忘记切换，可能导致线上项目请求错误的接口。
  • 难以管理：项目规模越大，硬编码的配置越分散，越难维护。

因此，引入环境变量，把不同环境下的配置抽离出来，统一管理，就显得非常必要。

2. 环境变量可以是什么？

环境变量并不是局限在“接口地址”这么简单，它可以涵盖很多方面。以一个典型的前端工程为例：

常见的环境变量类型

  1. 运行模式相关
    • NODE_ENV=development | production | test
    • 用来区分开发、生产、测试环境。
  2. 服务配置相关
  3. 功能开关
    • VITE_ENABLE_MOCK=true
    • VITE_ENABLE_SENTRY=false
    • 控制是否开启某些特性，比如 Mock 数据、错误上报。
  4. 第三方服务相关
    • VITE_GA_ID=UA-123456
    • VITE_FIREBASE_KEY=xxxxxx
    • 用来存储第三方 SDK 的 key（注意不能存放敏感的服务端密钥）。
  5. 构建信息
    • VITE_APP_VERSION=1.0.0
    • VITE_BUILD_TIME=2025-09-01 10:00:00
    • 方便前端展示版本号或调试。

特别注意

  • 前端环境变量不能存放敏感信息，例如数据库密码、服务端秘钥，因为前端代码最终会被打包成静态文件，用户在浏览器中就能看到所有变量。
  • 前端工程工具通常会规定一个前缀，比如 Vite 要求变量以 VITE_ 开头，Next.js 要求以 NEXT_PUBLIC_ 开头，用来区分哪些变量是允许暴露给前端的。

3. 环境变量的加载顺序

环境变量的来源有很多，比如系统环境、配置文件、构建工具的默认值。不同的前端工具会有不同的加载策略，但大体流程类似。以 Vite 为例：

Vite 中的加载顺序

  1. 系统环境变量

    • 来自 process.env，比如终端执行时传入：
TEXT
NODE_ENV=production vite build

  1. 项目根目录下的 .env 文件

    • 通用配置，所有环境都会加载。
    • .env

  2. 针对特定模式的 .env.[mode] 文件

    • .env.development
    • .env.production
    • .env.test

  3. 本地专用的 .env.local 文件

    • .env.local
    • .env.development.local
    • .env.production.local
    • 不会提交到 Git，用来存放开发者本地的特殊配置。

最终的加载优先级大致是：

TEXT
系统环境变量 < .env < .env.[mode] < .env.local < .env.[mode].local

后加载的会覆盖前面已经存在的变量。

其他工具的情况

  • Webpack + dotenv：需要手动配置 dotenv，加载逻辑和 Vite 类似。
  • Next.js：同样支持 .env、.env.local、.env.production 等，加载优先级和 Vite 接近。

总结

  • 环境变量 是运行环境下的一组键值对，用来抽离配置，避免硬编码。
  • 在前端工程中，环境变量可以包含接口地址、功能开关、第三方服务配置、构建信息等。
  • 环境变量有严格的加载顺序，不同环境下的 .env 文件可以叠加覆盖。

掌握环境变量的原理和使用方式，能让前端工程的 配置更加灵活、代码更易维护、部署更可控。