为何Vite项目中使用import.meta.env读取环境变量时抛出TypeError？

问题详情 #

我正在开发一个项目，希望使用Vite的环境变量机制（而非dotenv）来访问环境变量，不过已经安装了dotenv包。完全按照Vite官方文档中的示例配置：

.env 文件内容 #

VITE_SOME_KEY=123
DB_PASSWORD=foobar

main.js 文件内容 #

console.log(import.meta.env.VITE_SOME_KEY); //预期输出："123"
console.log(import.meta.env.DB_PASSWORD); //预期输出：undefined

运行时出现错误：

console.log(import.meta.env.VITE_SOME_KEY); // "123"
                            ^

TypeError: Cannot read properties of undefined (reading 'VITE_SOME_KEY')
    at file:///Users/oluwajolasun/Documents/Software%20Engineering/Projects/env%20test/env-test/main.js:1:29
    at ModuleJob.run (node:internal/modules/esm/module_job:262:25)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:485:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:109:5)

Node.js v22.5.1

项目文件夹结构：

解决步骤 #

1. 必须通过Vite启动项目 #

import.meta.env是Vite在构建或开发阶段注入的环境变量，直接用node main.js运行Node.js脚本是不生效的，Node本身不支持这个Vite专属语法。正确启动方式：

• 开发环境：执行 npm run dev
• 预览生产构建产物：先执行 npm run build，再执行 npm run preview

2. 检查package.json的脚本配置 #

确保package.json里有正确的Vite命令脚本：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

3. 移除dotenv干扰（可选） #

如果确定不需要dotenv，直接卸载避免冲突：

npm uninstall dotenv

4. 确认.env文件位置 #

.env文件必须放在项目根目录（和package.json、vite.config.js同级），从你的文件夹结构看位置正确，无需调整。

5. 更新Vite到最新版本 #

旧版本Vite可能存在兼容性问题，执行更新：

npm update vite

内容的提问来源于stack exchange，提问作者Jay Jay