ReactJS中规范配置的环境变量渲染时为undefined如何排查

开发者阿泽

2026-9-1

核心认知误区

React 脚手架（CRA）的环境变量为构建时静态注入，不存在“页面跳转、刷新后环境变量被清空”的逻辑：打包阶段所有process.env.REACT_APP_*引用会被直接替换为硬编码的字符串值，代码上线后运行阶段根本不存在动态读取env的逻辑，跳转、刷新操作不会修改已经写入打包产物的静态值。
useRef的初始化表达式仅会在组件首次挂载时执行1次，后续重渲染不会重新计算初始值；如果首次挂载执行到useRef初始化逻辑时，环境变量还未被正确识别，后续ref中存储的错误值不会自动更新。
你的.env文件存在格式错误：CRA内置的env加载逻辑不会自动过滤等号两侧的空格，你写的REACT_APP_CLIENT_ID =xxx会被识别为键名是REACT_APP_CLIENT_ID （末尾带空格），和代码中无空格的键名不匹配，直接导致读取值为undefined。
代码拼接URL时错误使用了HTML转义字符&：JS字符串中拼接URL参数直接用&分隔即可，&是HTML文本中的转义写法，写在JS字符串里会被当成普通字符，导致URL参数解析失败。
额外代码错误：搜索按钮的type属性写法错误，type='{submit}'会被识别为字符串值{submit}，不会触发表单原生提交行为。

排查流程

首先修正.env文件格式，删除所有等号两侧的空格，修正后配置如下：

REACT_APP_CLIENT_ID=*************************
REACT_APP_REDIRECT_URI=https://swipewithspotify.vercel.app/
REACT_APP_AUTH_ENDPOINT=https://accounts.spotify.com/authorize
REACT_APP_RESPONSE_TYPE=token

完全重启本地开发服务：CRA仅在服务启动时读取一次.env文件，修改配置后热更新不会加载新的环境变量，必须重启服务才能生效。
在组件函数的最顶层（不要写在条件分支、回调、useEffect内部）直接打印process.env，确认首次渲染时所有REACT_APP_开头的变量都能读取到正确值，排除构建注入失败问题。
如果是生产部署到Vercel，需要在Vercel项目的环境变量配置页添加和本地同名的所有REACT_APP_*变量：本地.env文件不会被上传到部署平台，生产构建时会从平台配置读取变量，漏配会直接导致生产环境值为undefined。

修复实现

这类固定不变的配置拼接值不需要用useRef存储，直接定义为模块级常量即可，完全脱离组件渲染时序，不会出现初始化时机问题，修正后的代码：

// 写在组件外部，模块加载时就完成拼接，不受组件挂载、重渲染逻辑影响
const SPOTIFY_LOGIN_URL = `${process.env.REACT_APP_AUTH_ENDPOINT}?client_id=${process.env.REACT_APP_CLIENT_ID}&redirect_uri=${process.env.REACT_APP_REDIRECT_URI}&response_type=${process.env.REACT_APP_RESPONSE_TYPE}`;

// 组件内渲染逻辑
function App() {
  // ... 其他原有逻辑：token、logout、searchArtists、setSearchKey等
  return (
    <>
      {!token ?
        <a href={SPOTIFY_LOGIN_URL}>Login to spotify</a>
        :
        <button onClick={logout}>Logout </button>
      }
      {
        token ?
          <form onSubmit={searchArtists}>
            <input type='text' onChange={e => setSearchKey(e.target.value)} placeholder='search for a song or artist' />
            <button type='submit'>Search</button>
          </form>
          :
          <h2>Please login</h2>
      }
    </>
  )
}

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