首次部署Node.js TypeScript项目至cPanel遇503错误求指导

先排查当前503错误的核心原因 #

• 检查Node.js应用状态：进入cPanel的「Node.js Selector」，找到你的项目，确认状态是否为Running。若为「Stopped」，点击「Start」后查看「Logs」按钮里的启动日志，定位报错（比如依赖缺失、编译失败、端口冲突）。
• 确认端口配置：绝对不要在代码里硬写固定端口，必须使用cPanel自动分配的环境变量端口：

  const port = process.env.PORT || 3000;
  app.listen(port, () => {
    console.log(`Server running on port ${port}`);
  });
  

• 核对域名映射：确保「Node.js Selector」中设置的「Application Root」和「Application URL」对应正确，URL不要与Apache默认站点路径冲突。

完整的TypeScript项目部署流程 #

1. 本地项目准备 #

• 确保package.json包含编译、启动脚本，示例：

  {
    "scripts": {
      "build": "tsc",
      "start": "node dist/index.js"
    },
    "devDependencies": {
      "typescript": "^5.0.0"
    }
  }
  

• 本地执行npm run build，确认生成dist（或你配置的输出目录），且npm start能正常启动服务。
• 执行npm install生成package-lock.json，固定依赖版本。

2. 上传项目到服务器 #

• 通过cPanel「文件管理器」或FTP，将项目文件（排除node_modules）上传到服务器子目录（比如public_html/ts-node-app，不要直接覆盖public_html根目录）。

3. 配置cPanel Node.js应用 #

• 打开cPanel的「Node.js Selector」，点击「Create Application」：
  • Node.js Version：选择与本地开发一致的版本（如18.x）
  • Application Root：选择你上传的项目目录（如ts-node-app）
  • Application URL：设置访问域名/子域名（如your-domain.com）
  • Application Startup File：填写编译后的入口文件路径（如dist/index.js）
• 点击「Create」完成创建。

4. 安装依赖并编译 #

• 打开cPanel「终端」，切换到项目目录：

  cd public_html/ts-node-app
  

• 安装依赖：

  npm install
  

• 编译TypeScript代码：

  npm run build
  

5. 启动并验证 #

• 返回「Node.js Selector」，找到你的应用点击「Start」。
• 点击「Open」访问应用，若仍出现503，再次查看「Logs」定位问题：
  • 若日志显示module not found：确认npm install执行成功，或检查package-lock.json是否上传
  • 若应用启动后立即停止：先在本地测试npm start是否能稳定运行，排查代码中的未捕获异常

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