在NameCheap cPanel部署NestJS服务/API失败求助

核心排查方向 #

1. 启动脚本与入口文件匹配 #

检查package.json的scripts配置，生产环境必须指向编译后的JS文件，不能用开发环境的nest start。正确的启动脚本示例：

"scripts": {
  "start": "node dist/main.js",
  "start:prod": "node dist/main.js"
}

cPanel的Node.js App默认调用npm start，确保这个脚本直接指向编译后的入口文件。

2. 文件路径与权限 #

• 确认package.json直接放在cPanel创建的应用根目录下（比如/home/你的用户名/nest-basic），dist文件夹也直接在根目录，不要嵌套子文件夹。
• 通过cPanel文件管理器调整权限：将dist文件夹及内部所有.js文件设为755，package.json设为644——权限错误会导致Node.js无法读取文件。

3. 查看启动日志（最关键） #

进入cPanel的Setup Node.js App，找到你的应用并点击Logs标签页，这里会显示启动失败的具体原因：

• 若提示Cannot find module：检查dist/main.js是否上传完整，或启动脚本路径写错，也可能是核心依赖（比如@nestjs/core）未安装。
• 若提示端口相关错误：无需手动指定固定端口，cPanel会自动分配并通过process.env.PORT注入，你的代码await app.listen(process.env.PORT || 3000)写法没问题，||3000不会在cPanel环境生效，忽略即可。
• 若提示CORS相关错误：确认全局CORS配置正确，示例：

// main.ts
app.enableCors({
  origin: '*', // 排查阶段可先开全局，生产环境建议指定具体域名
  credentials: true
});

4. 反向代理与URL映射 #

cPanel的Node.js App会自动配置反向代理，将你设置的Application URL映射到Node.js服务。比如你设置的URL是https://你的域名.com/nest-basic，访问该地址时请求会转发到NestJS服务的/路径，所以根接口GET /应返回Hello World——不要尝试直接访问端口，cPanel不允许外部直接访问Node.js服务端口。

修正后的部署步骤 #

1. 本地准备：
   • 执行nest build确保dist文件夹生成完整。
   • 执行npm install --production安装仅生产依赖（可选，也可让cPanel执行NPM Install，避免本地与服务器的依赖版本差异）。
   • 打包package.json、package-lock.json、dist文件夹（node_modules可不上传，由cPanel安装）。
2. cPanel操作：
   • 创建Node.js应用时选择Production模式，指定正确的根目录。
   • 上传文件后，在Setup Node.js App的Application Startup File手动填写dist/main.js（避免cPanel自动识别错误）。
   • 执行NPM Install后启动应用，立即查看日志确认启动状态。

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