Vue3项目中环境变量不生效 配置.env后读取输出undefined

• 不满足内置变量白名单规则
  • Vite构建的Vue3项目，默认仅将携带VITE_前缀的环境变量静态注入到浏览器可访问的代码环境中，无此前缀的FOO变量会在构建阶段被直接过滤，不会被打包进客户端运行时。需将.env内的变量名修改为VITE_FOO=实际值，匹配内置白名单要求。
  • 基于Vue CLI搭建的Vue3项目，对应白名单规则要求变量必须携带VUE_APP_前缀，否则无法被客户端代码读取。
• 读取API使用错误
  • Vite构建的Vue3项目，浏览器运行环境没有直接暴露完整的Node层process.env对象，直接调用process.env.FOO自然会返回undefined。客户端环境变量的官方读取入口是import.meta.env，对应测试代码需调整为console.log(import.meta.env.VITE_FOO)
  • 若需要在客户端读取无指定前缀的自定义变量，需在vite.config.js中通过define配置项手动完成全局映射，配置参考：

    // vite.config.js
    import { defineConfig } from 'vite'
    export default defineConfig({
      define: {
        'process.env.FOO': JSON.stringify(process.env.FOO)
      }
    })
    

• 环境变量加载流程失效
  • 确认.env文件放置在与package.json同级的项目根目录，放在src、components等子路径下的配置文件不会被构建工具扫描识别。
  • 环境变量仅在本地开发服务启动时完成一次性加载，修改.env配置后必须重启开发服务，热更新机制无法触达环境变量的读取流程。
  • 配置文件命名需匹配当前运行模式：执行npm run dev时默认加载.env、.env.development配置，执行生产构建npm run build时默认加载.env、.env.production配置，若将变量写在和当前运行模式不匹配的命名文件中，会出现读取失效。
• 配置文件格式解析异常
  • 检查.env内的变量书写格式，避免等号两侧留多余空格、变量值包裹多余引号，例如VITE_FOO = "测试值"这类不规范写法会导致解析失败，最终读取结果为undefined。

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