cPanel Setup Node.js App中Next.js生产环境环境变量未生效求助

我之前也碰到过一模一样的坑！用cPanel的Node.js插件部署Next.js时，手动添加的服务器端环境变量经常出现找不到的情况，明明在面板里配置了，process.env里就是看不到，折腾了好一阵才搞定。下面是我亲测有效的几个排查和解决办法：

• 严格遵守变量命名规范：cPanel的Node.js插件对环境变量名有要求，必须是大写字母+下划线的格式，比如API_SECRET_KEY，不能用小写、连字符或者其他特殊字符。哪怕你本地开发时用了小写，到cPanel里必须改成符合要求的格式，否则变量根本不会被加载到Node进程里。

• 确认变量添加到对应应用的环境中：别犯低级错误！cPanel里每个Node.js应用都有独立的环境配置，一定要进入你当前Next.js应用的「Environment Variables」界面添加变量，而不是加到全局环境或者其他应用的配置里。

• 彻底重启应用（别只点面板的重启按钮）：有时候面板的“Restart”按钮只是浅层次重启，环境变量缓存没清掉。正确操作是：先点「Stop」停止应用，等10-15秒再点「Start」启动；如果还是不行，建议通过SSH登录服务器，手动杀掉Node进程再重启：

  # 找到你的Next.js应用进程
  ps aux | grep node
  # 杀掉进程（替换成你的PID）
  kill -9 12345
  

  再回到cPanel启动应用，这样能确保新的环境变量被加载。

• 一定要在服务器端在线构建Next.js：如果你是本地执行npm run build后把.next文件夹上传到cPanel，那本地的.env文件内容会被打包到构建产物里，cPanel的环境变量根本不会覆盖这些内容。正确的做法是：只上传源码到服务器，在cPanel的Node.js插件里设置「Build Command」为npm run build，让cPanel在服务器上完成构建，这样构建过程会自动读取面板里配置的环境变量。

• 排查是否有本地.env文件干扰：检查服务器上的项目根目录，如果存在.env.local、.env.production这类文件，cPanel的Node.js插件会优先读取这些文件里的变量，而不是你手动添加的。删掉这些文件，或者清空里面的内容，再重启应用试试。

• 用测试脚本验证变量是否被加载：在项目根目录创建一个简单的测试脚本test-env.js：

  console.log("环境变量列表：", process.env);
  

  然后在cPanel的Node.js插件里点击「Run Script」执行这个文件，看输出里有没有你的变量。如果有，说明是Next.js的代码问题；如果没有，那就是cPanel的变量配置没生效，可能需要联系主机商检查插件版本或者服务器配置。

我当时的问题就是本地构建后上传导致的，改成服务器端在线构建就立刻解决了。你可以按这个顺序排查，应该能找到问题所在。

内容的提问来源于stack exchange，提问作者Paul Şular