Vite/Rollup 环境变量全攻略：`import.meta.env` 如何让你的配置飞起来

你是否还在为开发环境和生产环境的 API 地址切换而反复修改代码？或者被“不小心提交了敏感信息”的惊吓吓得睡不着觉？作为混迹前端圈十年的老司机，我曾被这些问题折磨得头发掉光。直到我深入研究了import.meta.env——这个 Vite 和 Rollup 项目中的“隐形助手”，才真正体会到什么叫“配置自由”。今天，我就带你拆解它的原理、用法和避坑指南，让你从此告别配置地狱。

一、import.meta.env是什么？为什么它这么香？

在现代前端构建工具中（Vite、Rollup 等），import.meta.env是一个在构建时自动注入的只读对象，它把环境变量“安全地”暴露给你的代码。
核心价值：

• ✅安全：敏感信息（如 API 密钥）不会被硬编码进源码，也不会被提交到 Git
• ✅灵活：一套代码适配多环境（开发/测试/生产）
• ✅高效：构建时直接替换变量，生成最小化生产包

为什么叫“meta”？
import.meta是浏览器原生 API（用于模块元数据），Vite/Rollup 利用它在构建阶段注入变量，不是运行时动态获取。这意味着在浏览器中打印import.meta.env会看到字符串（如"development"），而不是对象。

💡真实案例：
以前项目里写const API = process.env.NODE_ENV === 'production' ? 'https://prod.api' : 'https://dev.api'，现在只需const API = import.meta.env.VITE_API_URL，简洁又安全。

二、常见属性 & 配置实战：从 .env 文件开始

1.环境变量命名规则（Vite 专属，Rollup 需额外配置）

• Vite：变量必须以VITE_开头（如VITE_API_URL），否则会被忽略（安全设计！）
• Rollup：原生不支持，需用插件（如@rollup/plugin-inject或vite-plugin-environment）注入。

2.配置文件示例

在项目根目录创建.env文件（Vite 会自动识别）：

# .env.development VITE_API_URL="https://dev.api.com" VITE_APP_TITLE="开发版 App" # .env.production VITE_API_URL="https://prod.api.com" VITE_APP_TITLE="正式版 App"

3.在代码中使用

// main.jsconsole.log(import.meta.env.MODE);// 输出 "development" 或 "production"console.log(import.meta.env.VITE_API_URL);// 自动替换为对应环境的值// 用在 Vue/React 组件中constApp=()=>{return<h1>{import.meta.env.VITE_APP_TITLE}</h1>;};

⚠️关键注意：

• 变量名必须全大写（如VITE_API_URL），Vite 会自动转为import.meta.env.VITE_API_URL
• 未以VITE_开头的变量（如API_URL）不会注入！Vite 会直接忽略，避免误用。

三、Vite vs Rollup：环境变量的“微妙差异”

Rollup 配置示例（rollup.config.js）：

importinjectEnvfrom'@rollup/plugin-inject-env';exportdefault{plugins:[injectEnv({// 指定环境变量文件env:{VITE_API_URL:'https://rollup-api.com'}})]};

💡为什么 Vite 更简单？
Vite 内置了环境变量处理逻辑（基于@vitejs/plugin-vue），而 Rollup 是底层工具，需手动扩展。强烈建议：用 Vite 项目时，直接用 Vite 方式，别折腾 Rollup 配置。

四、避坑指南：90% 的人踩过的雷

1. 敏感信息泄露

   • ❌ 错误：在.env中写API_KEY=abc123（未以VITE_开头）
   • ✅ 正确：VITE_API_KEY=abc123，Vite 会自动过滤非VITE_变量。

2. 变量未生效

   • 检查：是否重启了开发服务器？（Vite 需热更新）
   • 检查：变量名是否漏了VITE_前缀。

3. TypeScript 类型缺失

   • 为避免 TS 报错，添加类型声明：

     // env.d.tsdeclaremodule'vite'{interfaceImportMetaEnv{VITE_API_URL:string;VITE_APP_TITLE:string;}}

4. 生产环境未替换

   • 确保build时使用vite build --mode production，否则会用development的变量。

五、进阶技巧：让环境变量更智能

1. 动态环境切换
   通过mode参数在命令行指定环境：

   vite build --mode staging# 使用 .env.staging

2. 结合 CI/CD 自动注入
   在 GitHub Actions 中设置环境变量：

   jobs:build:env:VITE_API_URL:${{secrets.PROD_API_URL}}# 从 GitHub Secrets 获取steps:-run:vite build

3. 为 Rollup 项目封装插件
   如果你用纯 Rollup，可以写个简单插件自动注入VITE_变量：

   // vite-env-plugin.jsexportdefaultfunctionviteEnv(){return{name:'vite-env',renderChunk(code){returncode.replace(/import\.meta\.env\./g,'import.meta.env.');}};}

结语：配置自由，从import.meta.env开始

import.meta.env不是“新特性”，而是现代前端工程化的基础实践。它用最小的代码代价，解决了环境配置的痛点——安全、简洁、可维护。记住：
✅ 变量名必须以VITE_开头（Vite 项目）
✅ 用.env文件管理，别写死在代码里
✅ Rollup 项目优先用 Vite，避免额外配置