Vue 3 + Vite + TypeScript环境变量无法正常使用问题求助

一、先卡基础规范 #

• 环境变量文件必须放项目根目录（和vite.config.ts同级），命名要对应模式：开发用.env.development，生产用.env.production，通用配置用.env
• 变量名必须以VITE_开头，比如VITE_API_URL=http://xxx，Vite只认这个前缀的变量，其他前缀的不会暴露给客户端
• 别把环境变量文件加到了忽略配置里，确保文件能被Vite读取到

二、代码里的正确调用姿势 #

• 别用process.env，Vite不支持Node的这个对象，要通过import.meta.env.VITE_XXX访问
• 示例代码：

// Vue组件或TS文件中使用
console.log(import.meta.env.VITE_API_BASE_URL);

三、解决TypeScript类型报错 #

如果TS提示import.meta.env找不到自定义变量，在src/vite-env.d.ts里补类型声明：

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string;
  // 把你自定义的其他环境变量都加上
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

四、Vite配置文件里用环境变量 #

要在vite.config.ts里用的话，得用Vite提供的loadEnv方法加载：

import { defineConfig, loadEnv } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig(({ mode }) => {
  // 根据当前运行模式加载对应环境变量
  const env = loadEnv(mode, process.cwd());
  
  return {
    plugins: [vue()],
    server: {
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL,
          changeOrigin: true,
        },
      },
    },
  };
});

五、最后查这些坑 #

• 修改环境变量后必须重启Vite开发服务器，它不会热更新环境变量
• 检查变量值的语法：字符串别加多余引号，特殊字符要转义
• 确认运行模式：npm run dev对应development模式，npm run build对应production模式，别搞混了对应的环境文件

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