cPanel部署Node.js/Express应用时自定义环境变量无法读取问题求助

cPanel的Setup Node.js App插件环境变量不生效属于高频部署问题，常见原因和对应修复方案如下：

1. 配置更新流程错误（最高发） #

cPanel的Node应用环境变量是写入到Passenger进程的启动配置文件中的，仅重启应用不会加载新的环境变量，正确的操作流程为：

• 完成环境变量修改后，先点击应用配置页的Update按钮保存全部配置
• 再点击Restart重启应用，新的环境变量才会被加载

2. 变量命名不符合要求 #

• 自定义变量不能与系统预留变量重名，包括NODE_ENV、PATH、USER、HOME、PWD等，这类变量会被系统默认值覆盖
• 变量名只能包含大写字母、数字、下划线，且不能以数字开头，不能包含特殊符号

3. 项目代码覆盖环境变量 #

检查项目的启动逻辑：

• 若使用dotenv加载本地.env文件，确认没有开启override: true配置，该配置会用.env文件的变量值覆盖系统传入的环境变量
• 不要在package.json的启动脚本、项目入口代码中手动赋值同名环境变量，会覆盖面板传入的配置

4. 插件版本BUG #

部分cPanel 90版本之前的Setup Node.js App插件存在配置缓存BUG，修改环境变量后即使执行更新操作也不会生效，可通过以下方式修复：

• 备份当前应用的根目录、启动脚本路径、Node版本、环境变量等配置
• 删除现有Node应用实例，重新创建并填入所有配置，新实例会正确加载自定义环境变量

验证方法 #

在项目入口文件的第一行加入日志打印：
console.log('TEST VAR: ', process.env.YOUR_CUSTOM_VAR)
重启应用后直接在面板的「查看日志」入口查看输出，不要通过业务接口返回验证，避免业务代码修改process.env导致结果不准。

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