Phusion Passenger部署Node.js应用出现初始化及加载执行报错

1. 优先核对本地与生产环境的一致性 #

• 校验Node.js版本匹配度：本地执行node -v得到的版本，需要和生产环境Passenger指定调用的Node版本完全一致。Passenger默认会调用系统全局的Node二进制文件，如果你项目适配的是其他版本，需要在Web Server配置中添加passenger_nodejs参数，指向对应版本的Node可执行文件路径。
• 校验依赖安装正确性：生产环境不要使用npm install安装依赖，必须执行npm ci完全按照package-lock.json的版本安装所有依赖，避免版本差异导致的运行错误。同时检查是否存在需要编译的原生依赖（比如node-gyp相关包），生产环境是否安装了对应的编译依赖（gcc、python、make等）。

2. 排查Passenger配置与权限问题 #

• 校验目录权限：确认Passenger运行时使用的用户身份，对项目根目录、node_modules目录、静态资源目录有读和执行权限，对需要写入的日志、临时文件目录有写权限，权限不足会直接导致应用初始化中断。
• 读取Passenger详细错误日志：不要只看前端返回的通用错误提示，找到对应服务的日志文件：
  • Nginx集成Passenger的日志默认路径为/var/log/nginx/error.log
  • Apache集成Passenger的日志默认路径为/var/log/apache2/error.log
    日志中会打印Node.js运行时的具体报错栈，可以直接定位到是模块缺失、环境变量缺失还是配置错误等具体问题。

3. 验证应用本身的生产环境兼容性 #

• 绕开Passenger直接启动应用：在生产环境命令行执行node 你的应用入口文件.js（比如node app.js），直接访问应用对应的端口确认是否能正常运行，如果直接启动正常，则可以确定问题完全出在Passenger的集成配置上，不需要再排查应用代码问题。
• 核对环境变量配置：确认生产环境已经配置了所有应用需要的环境变量，比如数据库连接地址、第三方服务密钥等，本地开发常用的.env文件默认不会在生产环境加载，缺失必要环境变量会导致应用初始化流程中断。

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