将NestJS部署到cPanel后持续出现503错误的排查求助

核心问题分析 #

报错MODULE_NOT_FOUND指向@nestjs/core，说明依赖未正确加载，结合503错误，本质是NestJS服务无法启动。以下是具体排查步骤：

1. 确认npm install的执行路径与依赖生成情况 #

• 检查cPanel Node.js应用的应用根目录是否与解压后的项目根目录匹配，确保npm install是在项目根目录执行的。如果zip解压后项目文件嵌套在子文件夹里，会导致依赖安装路径错误。
• 查看项目根目录下是否生成了node_modules文件夹，且其中存在@nestjs/core目录。如果没有，手动通过cPanel终端（或SSH）进入项目根目录，执行npm install或npm install --production，观察安装过程中是否有权限、网络相关报错。

2. 核对启动脚本与构建文件 #

• 检查cPanel Node.js应用的启动命令是否正确：生产环境应使用npm run start:prod，对应构建后的dist/main.js；若未构建则用npm run start。
• 确认本地执行npm run build生成的dist文件夹已完整上传至cPanel，且package.json的scripts中start:prod命令指向正确入口（比如node dist/main）。

3. 验证Node.js版本与应用重启 #

• 检查项目package.json的engines字段是否兼容Node.js 20.9.0，示例：

  "engines": {
    "node": ">=16.0.0"
  }
  

• 切换Node.js版本后，务必在cPanel Node.js应用界面点击Restart Application，确保版本切换生效。

4. 调整文件权限 #

• 将项目文件夹权限设为755，文件权限设为644。若node_modules或dist文件夹权限错误，会导致Node.js无法读取模块文件，可通过cPanel文件管理器批量调整。

5. 排查构建完整性与锁文件冲突 #

• 确保本地构建后的dist文件夹完整上传，避免遗漏编译后的文件。
• 若存在版本冲突，可删除线上的package-lock.json或yarn.lock文件，重新执行npm install。

6. 查看完整日志细节 #

• 除stderr.log外，查看cPanel Node.js应用日志选项卡中的其他日志（如access.log），获取更多启动报错信息，比如端口占用、其他依赖缺失等问题。

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