在 vite 项目中配置 .env 文件,核心原则是必须给变量名加上 vite_ 前缀,否则它们不会被暴露给客户端代码。具体做法是在项目根目录创建 .env.development 或 .env.production 文件,写入形如 vite_api_url=http://localhost:3000 的键值对,然后在 javascript 中通过 import.meta.env.vite_api_url 读取。vite 会自动根据当前运行模式(development 或 production)加载对应的环境变量文件。

如何区分开发环境和生产环境的配置?
要区分不同环境,只需创建后缀为 .env.development 和 .env.production 的文件。Vite 在启动开发服务器时默认使用 development 模式,而在构建时默认使用 production 模式。你可以在这两个文件中定义相同的变量名但不同的值,例如在开发环境中指向本地 Mock 服务,在生产环境中指向真实 API。Vite 会在运行时自动合并这些文件,优先级为:.env.local > .env.[mode] > .env,确保特定环境的配置能正确覆盖默认配置。

// .env.development VITE_API_URL=http://localhost:8080/api VITE_APP_TITLE=Dev App // .env.production VITE_API_URL=https://api.example.com VITE_APP_TITLE=Prod App // main.js console.log(import.meta.env.VITE_API_URL); // 开发环境输出 localhost:8080/api
上述代码展示了如何在不同环境文件中定义变量。在开发模式下,import.meta.env.VITE_API_URL 会读取 .env.development 中的值;而在生产构建后,它会读取 .env.production 中的值。这种机制允许开发者在不修改代码的情况下切换后端地址。注意,.env 文件中的通用变量会被所有环境继承,除非被同名的环境特定变量覆盖。
立即学习“Java免费学习笔记(深入)”;
为什么有些变量在浏览器中无法访问?
如果变量没有以 VITE_ 开头,或者试图在客户端代码中直接引用 Node.js 特有的全局变量,它们将无法在浏览器中访问。Vite 出于安全考虑,只将带有 VITE_ 前缀的变量注入到客户端 bundle 中。其他变量仅在服务端可用。此外,环境变量在构建时被静态替换,因此不能在运行时动态拼接变量名来访问,例如 import.meta.env['VITE_' + name] 虽然语法合法,但 Vite 的预处理可能无法正确识别非字面量的键,导致值为 undefined。最佳实践是始终使用明确的、带前缀的变量名。

// .env SECRET_KEY=123456 # 无前缀,仅服务端可用 VITE_PUBLIC_KEY=abc # 有前缀,客户端可用 // client.js console.log(import.meta.env.SECRET_KEY); // undefined console.log(import.meta.env.VITE_PUBLIC_KEY); // abc
这段代码验证了前缀规则。SECRET_KEY 因为没有 VITE_ 前缀,所以在客户端 import.meta.env 对象中不存在,读取结果为 undefined。而 VITE_PUBLIC_KEY 则正常显示其值。这解释了为什么某些配置在终端打印正常但在浏览器控制台报错或为空。开发者应检查变量命名是否符合规范,并确保敏感信息不放入带前缀的变量中,以免泄露到客户端。
基于 import.meta.env 的具体行为问题
当程序尝试访问一个未在 .env 文件中定义的 VITE_ 变量时,import.meta.env 对应属性的值为 undefined,而不是空字符串或报错。这意味着代码中必须进行显式的空值检查或使用默认值。例如,若 .env 中未定义 VITE_FEATURE_FLAG,则 import.meta.env.VITE_FEATURE_FLAG 返回 undefined。在逻辑判断中,if (import.meta.env.VITE_FEATURE_FLAG) 会进入 false 分支。这种行为要求开发者在初始化配置对象时提供 fallback 值,以避免运行时错误。


















