Vite 默认仅暴露以 VITE_ 开头的环境变量，若在 .env 中定义的密钥未加此前缀（如 REACT_APP_API_KEY），将无法通过 import.meta.env 访问，导致 API 请求因密钥为空或无效而失败。
vite 默认仅暴露以 `vite_` 开头的环境变量，若在 `.env` 中定义的密钥未加此前缀（如 `react_app_api_key`），将无法通过 `import.meta.env` 访问，导致 api 请求因密钥为空或无效而失败。
在 Vite 项目中，环境变量的安全机制与 Create React App（CRA）不同：*Vite 不自动识别 `REACTAPP前缀**，而是强制要求所有需在客户端代码中使用的变量必须以VITE_` 开头。这是出于安全考虑——避免意外暴露敏感配置，同时明确区分服务端与客户端可访问的变量范围。
✅ 正确配置步骤
-
在 .env 文件中声明变量（必须以 VITE_ 开头）
VITE_REACT_APP_API_KEY=your_actual_tmdb_api_key_here
⚠️ 注意：.env 文件需位于项目根目录（与 vite.config.js 同级），且不能包含空格、引号或注释（如 VITE_REACT_APP_API_KEY = "abc" ❌）。
-
在代码中通过 import.meta.env 安全读取
const apiKey = import.meta.env.VITE_REACT_APP_API_KEY; const getMovies = () => { if (!apiKey) { console.error('❌ API key is missing. Check your .env file and restart dev server.'); return; } fetch(`https://api.themoviedb.org/3/discover/movie?api_key=${apiKey}`) .then((res) => { if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`); return res.json(); }) .then((json) => console.log('✅ Movies fetched:', json)) .catch((err) => console.error('❌ Fetch failed:', err)); }; useEffect(() => { getMovies(); // ✅ 修正：原代码中误写为 cleanup 函数调用，应为主动执行 }, []);
? 常见误区与排查建议
- 变量名拼写不一致：确保 .env 中的键名（VITE_REACT_APP_API_KEY）与代码中引用的完全一致（大小写敏感）；
- 未重启开发服务器：修改 .env 后必须重启 npm run dev，Vite 不会热更新环境变量；
- 错误的钩子逻辑：原示例中 useEffect 的清理函数误调用了 getMovies()，应改为在依赖数组为空时主动执行；
- 生产环境验证：构建后（npm run build），可通过 dist/index.html 检查打包后的 JS 是否已内联正确密钥值（Vite 会在构建时静态替换 import.meta.env.*）。
? 扩展提示：环境变量分级管理
可结合 Vite 的 mode 支持多环境配置：
# .env.development VITE_REACT_APP_API_KEY=dev_key_123 # .env.production VITE_REACT_APP_API_KEY=prod_key_456
启动时指定模式：vite --mode production，Vite 将自动合并 .env + .env.production。
遵循 VITE_ 命名规范，是保障密钥可靠注入、API 调用成功的关键前提。
