.env 环境变量不生效怎么解决？process.env 读到 undefined 的 6 个原因

明明在 .env 里写了 API_KEY=xxx，代码里 process.env.API_KEY 却是 undefined——这几乎都不是玄学，而是下面 6 个具体原因之一。先按它们逐个排除。

① 改了 .env 没重启 dev（最常见）

成因：环境变量是进程启动时读进去的。dev 服务器已经在跑，你改了 .env 它不会自动重读。

修复：Ctrl+C 停掉，重新 npm run dev。这一步能解决一大半"读不到"。

② 前端变量缺 NEXT_PUBLIC_ 前缀（Next.js / Vite）

成因：出于安全，框架默认只把环境变量注入服务端。浏览器里要用的变量必须加前缀，否则在客户端永远是 undefined。

修复：

• Next.js：浏览器要读的变量改成 NEXT_PUBLIC_API_URL；
• Vite：改成 VITE_API_URL，代码里用 import.meta.env.VITE_API_URL。
• 密钥类（API key、token）不要加前缀，那样会泄露到前端。

③ 文件名或位置不对

成因：文件叫成了 env、.env.txt、放在了子目录，或该用 .env.local 的用了 .env。

修复：文件名就是 .env（或 .env.local），放在项目根目录（和 package.json 同级）。注意优先级：.env.local 会覆盖 .env。

④ 纯 Node 脚本没装 / 没加载 dotenv

成因：Next.js / Vite 内置读 .env，但纯 Node 脚本不会自动读，需要 dotenv。

修复：

npm install dotenv

脚本最顶部加载：

import "dotenv/config";   // 或 require("dotenv").config();

⑤ 变量名拼错 / 大小写 / 多了空格引号

成因：.env 里写成 API_KEY = xxx（等号两边空格）、加了引号、或代码里大小写对不上。

修复：.env 写成 KEY=value，等号两边不留空格、值不用加引号（除非含空格）；代码里的变量名和 .env 完全一致。

⑥ 构建/部署平台没配（线上 undefined）

成因：本地 .env 不会上传（也不该上传），Vercel / CI 上没配同样的变量，所以线上读不到。

修复：在 Vercel → Settings → Environment Variables（或 CI 的 Secrets）补齐，勾对 Production 环境，重新部署才生效。

快速验证一行

node -e "require('dotenv').config(); console.log(process.env.你的变量名)"

能打印出值，说明 .env 本身没问题，问题在框架前缀或重启；打印 undefined，回到 ③⑤ 查文件和拼写。

让 Codex 辅助

我在 .env 配了 X，但 process.env.X 是 undefined。
我用的是 Next.js / Vite / 纯 Node 脚本，这个变量在服务端还是浏览器用。
请判断最可能是前缀、重启、文件位置还是平台未配，给出对应修复。

风险提醒

• .env 必须进 .gitignore，别把密钥提交进仓库或公开。
• 给前端加前缀的变量等于公开，绝不要把密钥、token 加 NEXT_PUBLIC_ / VITE_。

相关工具

• 报错解释器
• Codex 工具页
• 项目报价助手

相关报错排查

同一套排查思路的常见报错，建议一起看：

• Vercel 部署失败怎么办
• npm run dev 能跑但 build 失败
• npm install 报错怎么解决

免责声明

本文成因与修复对应 Node / Next.js / dotenv 的通用行为，供学习和排查参考；涉及客户密钥、生产环境变量时需明确授权并人工复核。