在cPanel共享主机上使用Passenger部署Node.js应用
使用 cPanel 共享主机上的 Application Manager 和 Passenger 运行 Express 应用的逐步指南，涵盖重启、环境变量设置以及 503 错误解决方法。
许多 cPanel 共享主机都能很好地运行 Express 应用或 API 服务器，前提是该账户在 cPanel 的应用程序管理器背后具备 Phusion Passenger 所支持的 Node.js 功能。您无需自行配置 Nginx、Apache 反向代理或 PM2，因为 Passenger 会负责启动应用并路由请求至该应用。本指南涵盖了从确认相关功能已启用到诊断 503 错误的全流程部署步骤，最后还提供了发布前的检查清单。
您的托管账户所需条件
在上传任何内容之前，请先确认账户具备以下功能：
- Node.js 支持
- cPanel 应用程序管理器
- Passenger
- 终端或 SSH 访问权限
- npm
- 用于部署应用的域名或子域名
- 如果应用需要数据库，则还需具备数据库访问权限
如果找不到应用程序管理器，请让您的主机服务商启用 Node.js 和 Passenger。运行 CloudLinux 的主机可能会用不同的名称来标识该工具。
步骤 1：确认 Node.js 已安装
在 cPanel 中，打开Software，然后选择Application Manager（某些版本则会在网站管理选项下显示 Node.js 相关选项）。如果该页面能够打开，说明账户已准备就绪。
步骤 2：上传应用程序
使用文件管理器或 Git 将项目上传到您主目录下的某个文件夹中，例如：
/home/username/my-node-app
一个典型的项目结构如下所示：
my-node-app/
├── package.json
├── package-lock.json
├── app.js
├── src/
└── ...
请将源代码保存在 public_html 文件夹之外，因为浏览器可以直接请求该文件夹中的任何文件。
步骤 3：准备 package.json 并安装依赖项
该项目需要一个有效的 package.json 文件，其中要列出其依赖项以及启动脚本。以下是一个最简的 Express 示例：
{
"name": "my-node-app",
"version": "1.0.0",
"scripts": {
"start": "node app.js"
},
"dependencies": {
"express": "^5.1.0"
}
}
接着打开 cPanel 的 终端，进入项目文件夹并执行安装操作：
cd ~/my-node-app
npm install
这样就能在服务器上安装已列出的依赖项。如果有已提交的锁定文件，使用 npm ci --omit=dev 是一种更轻量且可复现的替代方法。
第 4 步：编写启动文件
Passenger 需要一个可启动的入口点，例如：
app.js
对于 Express 应用而言，该文件首先会加载 Express：
const express = require('express');
然后创建应用实例、定义路由并开始监听请求。下面的代码虽被压缩在几行内，但由于每条语句都以分号结尾，因此仍是有效的 JavaScript 代码。
const app = express();const PORT = process.env.PORT || 3000;app.get('/', (req, res) => {
res.send('Node.js application is working!');
});app.listen(PORT, '0.0.0.0', () => {
console.log(`Application running on port ${PORT}`);
});
为何端口必须来自 process.env.PORT
切勿将公共端口硬编码。Passenger负责决定请求如何到达您的进程，因此应从环境变量中读取端口，并设置本地备用值：
const PORT = process.env.PORT || 3000;
相同的代码在本地以3000端口运行时，使用Passenger的情况下也不会有任何变化。
第5步：在cPanel中注册应用程序
在应用程序管理器中，点击Create Application或Register Application。为应用命名，例如my-node-app，选择域名（如example.com）并将/设为基础URL，将项目文件夹设置为根目录，启动文件设为app.js，选择依赖项所支持的稳定Node.js版本，再挑选生产环境。之后点击Create或Deploy。生成的请求路径如下所示：
https://example.com
↓
Apache
↓
Passenger
↓
Node.js App
↓
app.js
Apache接收请求后，Passenger会将其转发到由启动文件启动的Node.js进程。
步骤6：设置环境变量
应在应用程序的设置中而非代码中定义环境变量。例如：
APP_ENV=production
DB_HOST=localhost
DB_DATABASE=mydb
DB_USERNAME=myuser
DB_PASSWORD=your_password
您的代码是通过 process.env 来读取这些值的：
process.env.DB_HOST
process.env.DB_DATABASE
process.env.DB_USERNAME
机密信息应仅保存在服务器端，绝不能出现在前端 JavaScript 中或 public_html 目录下的 .env 等可公开访问的文件中。
第 7 步：每次修改后重新启动
Passenger 会保持应用处于运行状态，因此只有通过应用程序管理器重新启动后，更改才会生效。在支持重启文件约定的情况下，终端也能实现相同功能：
mkdir -p ~/my-node-app/tmp
touch ~/my-node-app/tmp/restart.txt
Passenger 会监控 tmp/restart.txt 文件的修改时间，一旦该文件被修改，就会在下一个请求到来时重新启动应用，这非常适合用于部署脚本。
解决 503 服务不可用错误
您最可能遇到的错误就是这个：
503 Service Unavailable
503 错误很少意味着服务器宕机；通常是因为 Passenger 无法启动或无法连接到您的应用。请先手动运行一下该应用：
cd ~/my-node-app
node app.js
如果程序崩溃，先修复这个问题。如果能够启动，则检查常见的问题点。
错误的启动文件
应用程序管理器必须指向实际存在的、能够启动服务器的文件：
app.js
缺少依赖项
如果node_modules不存在或不完整，需要重新安装：
npm install
Node.js版本不兼容
查看终端使用的版本以及你的依赖项所要求的版本：
node -v
然后在应用程序设置中选择匹配的版本。
硬编码端口
确保服务器在正确的端口上监听：
process.env.PORT
而不是使用固定的公共端口。
缺少环境变量
确认凭证、API密钥、应用程序模式以及其他必需的数值都已设置；如果存在未定义的变量导致启动失败，也会出现503错误。
日志
Passenger或cPanel应用日志通常会显示确切的启动错误信息。
共享主机与VPS
这两种环境的区别主要在于谁来控制服务器。在cPanel共享主机上，其技术架构大致如下：
cPanel
│
├── Apache
├── Passenger
└── Node.js
│
└── Your Application
主机和Passenger负责管理Web服务器及进程。而在VPS上，你可以掌控每一层：
VPS
│
├── Nginx/Apache
├── Node.js
├── PM2
├── Firewall
├── SSL
└── Application
VPS提供了更大的控制权，通常更适用于资源需求高或需要高度定制的应用；可参阅将Node.js应用投入生产的实用框架。共享主机则以简化管理为代价放弃了这种控制权。
整洁的目录结构
规范的cPanel部署方式会让应用文件与公共Web根目录并存：
/home/username/
│
├── my-node-app/
│ ├── app.js
│ ├── package.json
│ ├── package-lock.json
│ ├── node_modules/
│ ├── src/
│ └── tmp/
│ └── restart.txt
│
└── public_html/
请求通过 Apache 和 Passenger 到达 my-node-app，而 public_html 中不包含任何服务器代码。
最终检查清单
在认为部署已完成之前，请确认：
- 账户已启用 Node.js
- 可用应用程序管理器
- 已选择兼容的 Node.js 版本
- 项目文件已上传到
public_html之外 - 存在
package.json文件 npm install执行完毕且无错误- 启动文件设置正确
- 服务器正在监听
process.env.PORT - 环境变量已配置完毕
- 环境模式已设置为生产环境
- 自上次修改后应用已被重新启动
- 域名能在浏览器中正常加载