Node.js+Express+MySQL API部署至cPanel共享主机遇503错误排查

一、cPanel Node.js应用配置问题 #

• 检查cPanel中Node.js应用的启动文件路径：本地用nodemon dbServer启动，线上启动文件需设为dbServer.js（注意后缀），且要对应子域名下的实际文件位置，避免因目录层级错误导致找不到启动文件。
• 核对Node.js版本：确保cPanel的Node.js版本与本地node -v输出的版本一致，版本差异可能引发依赖或语法兼容问题。
• 查看应用日志：在cPanel的Node.js应用管理页找到「Logs」选项，排查是否有启动失败的具体报错（如端口占用、文件缺失）。

二、启动脚本与文件结构问题 #

• 确认package.json的start脚本：本地用nodemon，线上需改为node dbServer.js（cPanel无需热重载工具），保证scripts中的start字段为node dbServer.js。
• 检查项目目录层级：上传解压后的项目根目录需对应cPanel子域名的指定目录，避免多套一层文件夹导致启动路径错误。

三、依赖与环境变量问题 #

• 重新执行npm install：在cPanel终端进入项目目录，执行npm install --verbose，查看是否有依赖安装失败（如部分包需要编译，服务器缺少对应环境）。
• 验证.env配置：
  • 数据库主机不要用localhost，需使用cPanel提供的数据库服务器地址（可从PHPMyAdmin的连接信息中获取）。
  • 数据库用户名、密码、库名要与PHPMyAdmin中创建的完全匹配，注意大小写和特殊字符。
  • 修改.env后需重启cPanel的Node.js应用，确保配置生效。

四、服务器进程与权限问题 #

• 端口配置：不要手动指定固定端口，改用process.env.PORT读取cPanel自动分配的端口，避免端口占用或权限问题。
• 文件权限：将项目文件权限设为644、目录权限设为755，防止因权限不足导致进程无法读取文件。
• 重启应用：在cPanel的Node.js应用管理页点击「Restart」，确保进程处于正常运行状态。

五、数据库连接问题 #

• 测试数据库连接：在dbServer.js开头添加简单的连接测试代码，将连接结果输出到日志，排查是否能成功连接到cPanel数据库。
• 核对数据库用户权限：确保创建的数据库用户拥有该库的读写权限，避免因权限不足导致createUser接口写入操作失败。

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