Next.js服务端代码未加载非NEXT_PUBLIC_前缀环境变量问题求助

核心原因排查 #

你遇到的生产环境非公开环境变量返回undefined的问题，通常是以下两个常见配置错误导致的：

1. 部署环境缺失对应env文件 #

你把BOT_EMAIL_USER这类服务端变量只写在了.env文件中，如果你的项目把.env加入了.gitignore，生产部署拉取代码构建时，仓库中不存在.env文件，Next.js自然无法读取到这些变量。

2. 变量访问位置错误 #

不带NEXT_PUBLIC_前缀的环境变量只会被注入到服务端运行时，如果你在客户端执行的代码中访问这些变量，必然返回undefined：

• Pages Router下：只有getStaticProps、getServerSideProps、API路由这些服务端运行的逻辑能读取非公开变量，组件的渲染方法、useEffect、前端事件处理函数都属于客户端运行逻辑，无法读取
• App Router下：只有没有添加'use client'指令的服务端组件、Server Action、路由处理程序能读取非公开变量，标注了客户端的组件完全无法访问这类变量

修复方案 #

• 针对env文件缺失问题，三选一即可：
  • 若.env中没有敏感信息，把它从.gitignore中移除，确保部署时能加载到
  • 把BOT_EMAIL_USER这类非敏感的服务端变量也添加到.env.production文件中，该文件通常不会被忽略，部署时会随代码一起打包
  • 直接在部署平台的环境变量配置面板手动添加这些服务端变量，平台配置的变量优先级高于本地env文件
• 针对访问位置错误问题：
  不要在客户端代码中直接读取非公开环境变量，如果你需要在前端触发用到这些变量的逻辑，封装一个服务端API接口，客户端调用接口后由服务端读取变量处理对应逻辑，再把结果返回给前端，全程不会泄露敏感信息。

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