Vite应用部署至Netlify时环境变量缺失/为空？求技术帮助

以下是针对该问题的逐一排查步骤，覆盖Vite与Netlify环境变量配置的核心要点：

1. 确认Vite环境变量命名规则 #

Vite要求客户端可访问的环境变量必须以VITE_为前缀，无论在Netlify后台还是代码中都要严格遵循：

• Netlify后台的变量名需设为VITE_API_KEY（而非API_KEY）
• 代码中通过import.meta.env.VITE_API_KEY读取，不能省略前缀或写错名称

2. 触发Netlify重新部署 #

修改Netlify环境变量后，必须手动触发重新部署（站点后台→部署→触发部署），旧的构建产物不会自动加载新变量。

3. 检查代码中的变量引用方式 #

• 避免在import语句中直接使用环境变量，这类写法在构建阶段无法被Vite正确解析，需将变量逻辑放在运行时：

  // 错误写法
  import apiClient from `./api/${import.meta.env.VITE_API_KEY}`;
  
  // 正确写法
  const apiClient = await import(`./api/${import.meta.env.VITE_API_KEY}`);
  

• 添加变量存在性校验，便于定位问题：

  const apiKey = import.meta.env.VITE_API_KEY;
  if (!apiKey) {
    console.error("API密钥未配置，请检查Netlify环境变量");
  }
  

4. 核对Netlify后台配置细节 #

• 确认变量添加在目标站点的环境变量中，而非Netlify账户全局变量
• 变量作用域需包含Build和Deploy（默认配置即可，若修改过需还原）
• 变量值不要添加多余引号，直接输入纯密钥字符串（例如abc123而非"abc123"）

5. 检查Netlify构建配置 #

• 确认站点构建命令为npm run build（对应Vite默认的构建脚本）
• 若使用netlify.toml，确保[build]配置正确，不要在配置文件中重复定义环境变量（优先使用后台配置）：

  [build]
    command = "npm run build"
    publish = "dist"
  

6. 敏感密钥的安全处理 #

若API密钥为敏感信息，绝对不能直接放在客户端环境变量中（会被用户在浏览器代码中看到），需通过Netlify Functions做接口代理：

1. 在项目根目录创建netlify/functions/proxy-api.js
2. 在函数中读取Netlify的非前缀环境变量（无需VITE_），转发请求到目标API
3. 前端代码请求该Netlify函数地址，而非直接调用目标API

7. 查看Netlify构建日志 #

前往Netlify部署日志，搜索你的环境变量名（如VITE_API_KEY），确认构建过程中是否成功加载变量：

• 若日志显示变量为undefined，说明Netlify未将变量传入构建流程，需重新检查后台变量与站点的关联

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