React项目中REACT_APP_环境变量返回undefined问题求助

API 探路者

2026-6-27

解决React环境变量返回undefined的问题

检查.env文件的命名与位置
确保文件是.env（注意开头的英文点），且放在项目根目录（和package.json同级），不要放到src或其他子目录。Mac系统下如果创建时遇到问题，用终端命令创建：touch .env，避免系统自动添加多余后缀。
确认变量前缀与拼写
React官方脚手架要求环境变量必须以REACT_APP_开头，你的变量名REACT_APP_MAPBOX_TOKEN是合规的，但要仔细检查有没有大小写错误、下划线漏写这类低级问题。
规范.env文件格式
变量值不要加引号（你已经做到），同时等号前后不能有空格，比如不能写成REACT_APP_MAPBOX_TOKEN = pk.ey...，必须是REACT_APP_MAPBOX_TOKEN=pk.ey...。文件内注释要以#开头，避免注释格式干扰变量读取。
彻底重启开发服务
修改.env文件后，必须完全关闭当前的React服务（终端按Ctrl+C），再重新运行npm start或yarn start，仅刷新浏览器页面无效。
排查多环境文件冲突
如果项目里存在.env.development、.env.production这类环境专属文件，开发环境会优先加载.env.development。如果该文件里有同名变量但值为空，就会覆盖.env里的配置导致undefined。
打印process.env验证加载情况
在app.jsx里先打印整个process.env：
```
console.log(process.env);
```
查看输出里是否包含REACT_APP_MAPBOX_TOKEN，如果没有说明.env文件未被正确加载；如果有但值异常，再回头检查文件内容。
Mac系统隐藏文件验证
Mac默认隐藏以.开头的文件，可在项目根目录终端执行ls -a，确认.env确实存在，避免误创建成了没有开头点的env文件。
自定义脚手架需手动配置dotenv
若你不是用官方create-react-app，而是自行配置的Webpack，需要手动安装并配置dotenv-webpack插件：
安装依赖：npm install dotenv-webpack --save-dev
Webpack配置文件中添加：
```
const Dotenv = require('dotenv-webpack');

module.exports = {
  plugins: [
    new Dotenv()
  ]
};
```