别再混用了！import.meta.env 与 process.env 的本质差异一次讲透

先说结论：import.meta.env 更偏“现代前端构建工具（Vite）语义”，process.env 更偏“Node 语义（Webpack/Node 运行时）”。

在纯前端项目里，它们看起来都能“读环境变量”，但本质来源、注入时机、可见范围和迁移成本都不一样。

如果现在正在构建 Vue3/Vite 或 React/Vite 项目的话，优先用 import.meta.env；如果是 Webpack 老项目、Node 脚本或服务端代码，process.env 依然是主角。

1）import.meta.env 是什么？

import.meta.env 是 ESM + Vite 提供的环境变量访问方式。它不是 Node 原生对象，而是由构建工具在开发/打包阶段注入。

常见特征

• 内置变量：MODE、DEV、PROD、BASE_URL
• 自定义变量默认要有前缀（Vite 默认 VITE_），例如：VITE_API_BASE
• 能在前端代码中直接访问（最终会被构建替换）

// .env.development
VITE_API_BASE=/api
VITE_APP_TITLE=Demo

// 业务代码
const baseURL = import.meta.env.VITE_API_BASE
const isDev = import.meta.env.DEV

适用场景

1. Vite 项目的前端业务代码
2. 按环境切换 API 地址、开关日志、控制埋点
3. 希望享受更清晰的前端变量约束（前缀暴露机制）

2）process.env 是什么？

process.env 是 Node.js 运行时里的环境变量对象。

在服务端（Node）代码中，它天然存在；在前端项目中能不能用，取决于打包器是否做了注入/替换（如 Webpack 的 DefinePlugin）。

常见特征

• Node 端“原生可用”
• 前端中常见于旧工程（Vue CLI/Webpack）
• 常见变量：process.env.NODE_ENV、process.env.VUE_APP_XXX

// Vue CLI / Webpack 常见
if (process.env.NODE_ENV === 'production') {
  // 生产逻辑
}
const baseURL = process.env.VUE_APP_BASE_API

适用场景

1. Node 服务端代码（Express、Nest、脚本工具）
2. Webpack 系项目前端代码
3. CI/CD 中通过系统环境变量注入配置

3）核心区别（重点）

下面这张表抓住最关键差异：

4）代码对比案例

案例 A：按环境切 API 地址

Vite 写法：

const requestBaseURL = import.meta.env.VITE_API_BASE

Webpack/Vue CLI 写法：

const requestBaseURL = process.env.VUE_APP_BASE_API

案例 B：开发环境打印日志

Vite：

if (import.meta.env.DEV) {
  console.log('dev log')
}

Webpack/Node：

if (process.env.NODE_ENV !== 'production') {
  console.log('dev log')
}

案例 C：从 Vue CLI 迁移到 Vite 的典型坑

很多人会直接把旧代码搬过来：

// 旧代码
const url = process.env.VUE_APP_BASE_API

在 Vite 前端中应改为：

const url = import.meta.env.VITE_API_BASE

并把 .env 变量从 VUE_APP_BASE_API 改成 VITE_API_BASE。

5）实践建议（避免踩坑）

1. 前后端变量分层

   • 前端可见：只放“可公开配置”，用 VITE_ 前缀
   • 服务端敏感项（密钥/私钥）：只放 process.env（Node 端），不要暴露给前端

2. 不要混用语义

   • Vite 前端代码统一 import.meta.env
   • Node 脚本、SSR 服务端逻辑统一 process.env

3. 迁移时一次性改全

   • 变量名前缀、读取方式、构建脚本、文档一起更新
   • 建议加一条 lint/代码审查规则，禁止在 Vite 前端里继续写 process.env.xxx

结语

import.meta.env 是“面向前端构建时”的环境注入接口，process.env 是“面向 Node 运行时”的环境变量接口。

它们都能“读配置”，但不在同一个语义层。把语义边界划清，项目会更稳定，迁移成本也会更低。

好啦！今天的知识点就分享到这里吧，希望读完对你的职业素养有一个质的提升。