Next.js TypeScript项目中process.env变量无法读取的原因及解决方法

算力阿峰

2026-8-12

.env.local变量无法通过process.env访问的原因及解决办法

可能的原因

框架环境限制：如果用的是Next.js这类框架，客户端代码里的环境变量必须以特定前缀开头（比如NEXT_PUBLIC_）才能被访问，普通变量仅在服务端生效。要是你的代码在客户端执行，没加前缀自然拿不到值。
未加载环境变量：Node.js默认不会自动读取.env.local文件，很多项目需要依赖dotenv包来加载这类环境配置文件，没装或没配置的话就读不到变量。
文件路径或命名错误：确认文件名是.env.local（注意开头的点），且确实放在项目根目录（和package.json同级），不是某个子文件夹里。
服务未重启：修改.env.local后，必须重启开发服务器，否则新的变量不会被加载到进程中。
变量格式错误：检查变量定义的格式，比如不要在等号两边加空格（WEBSOCKET_VARIABLE = THIS_IS_TEXT这种写法会导致读取异常），字符串值也不需要额外加引号。

适配客户端前缀要求：如果是在客户端代码中使用这个变量，给变量名加上框架要求的前缀，比如Next.js里改成NEXT_PUBLIC_WEBSOCKET_VARIABLE=THIS_IS_TEXT。
安装并配置dotenv：
1. 安装依赖包：npm install dotenv --save-dev
2. 在项目的入口文件（比如server.js或index.js）顶部添加加载代码：
```
// CommonJS 格式
require('dotenv').config({ path: '.env.local' })
```
  要是用的是ES模块：
```
// ES Module 格式
import dotenv from 'dotenv';
dotenv.config({ path: '.env.local' });
```
核对文件位置和命名：确认.env.local文件在项目根目录，文件名没有拼写错误（比如别写成env.local漏了开头的点）。
重启开发服务：关掉当前运行的开发服务器，重新执行npm run dev或项目对应的启动命令。
修正变量定义格式：把变量改成正确的写法，比如WEBSOCKET_VARIABLE=THIS_IS_TEXT，去掉等号两边的空格和多余的引号。