如何在 Namecheap 共享主机上部署 NestJS

在 Namecheap 共享主机上部署 NestJS 与部署静态网站或 PHP 应用不同。你不能只是上传文件并期望它能正常运行。

你必须将 TypeScript 编译为 JavaScript，安装生产环境依赖项，并使用 cPanel 通过 Passenger 来管理该过程。

在找到正确的方法之前，我曾遇到过文件夹为空、缺少构建文件以及 Redis 连接中断等问题。以下是经过验证的工作流程。

设置逻辑

请求遵循以下路径： • 浏览器或 API 客户端 • 域名和 HTTPS • Namecheap 上的 Apache / Passenger • app.js（桥接文件） • dist/main.js（编译后的代码） • NestJS 应用

核心要求

• 一个支持 Node.js 的 Namecheap 托管账户 • 访问 cPanel 和 SSH/终端的权限 • 一个可运行的 NestJS 项目 • 数据库或 Redis 的生产环境凭据

步骤 1：准备代码

不要使用硬编码的端口。在你的 src/main.ts 中，使用 process.env.PORT：

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT || 4000);
}

步骤 2：整理依赖项

将 @nestjs/common 和 @nestjs/core 等运行时包移动到 package.json 的 dependencies 部分。如果它们留在 devDependencies 中，你的应用在生产环境中会崩溃。

步骤 3：构建并创建桥接文件

Namecheap 运行的是 JavaScript，而不是 TypeScript。 • 在本地运行 npm run build。 • 确认 dist/main.js 存在。 • 在项目根目录下创建一个 app.js 文件，并写入这一行：require('./dist/main');

这个 app.js 将作为 Passenger 的入口点。

步骤 4：部署策略

最安全的方法是在本地构建并上传构建产物： • 上传 app.js • 上传 dist/ 文件夹 • 上传 package.json 和 package-lock.json • 在 Namecheap 上运行：npm ci --omit=dev

永远不要上传本地的 node_modules 文件夹。在你的电脑上构建的原生模块无法在 Linux 服务器上运行。

步骤 5：配置 cPanel

在 cPanel 中前往 Setup Node.js App： • 选择正确的 Node.js 版本。 • 将 mode 设置为 Production。 • 将 Application root 设置为你的文件夹。 • 将 Application startup file 设置为 app.js。

步骤 6：环境变量

直接在 cPanel 的 Node.js 界面中添加你的密钥（如 DATABASE_URL 或 API 密钥）。你也可以在根目录下使用 .env 文件，但要确保它不在 dist 文件夹内。修改后请重启应用。

常见问题排查

• EADDRINUSE：你可能有一个手动运行的进程。请让 Passenger 来管理应用。 • Cannot find module：你的构建文件缺失，或者 app.js 中的路径错误。 • Redis connection failed：检查 Namecheap 是否允许通过你的 Redis 端口进行出站连接。你可能需要联系 Namecheap 支持团队来开启它。

来源：https://dev.to/adesoji/how-to-deploy-and-run-a-nestjs-app-on-namecheap-shared-hosting-5c45