在 Plesk 上部署 Node.js 应用程序
通过 Plesk 上线 Node.js 应用程序:目录结构、启动文件、npm 依赖项、环境变量、日志以及常见错误的解决方法。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
本指南介绍如何通过 Plesk 将 Node.js 应用程序发布到您的域名,安装依赖项并完成配置,然后确认它能够正常响应。
前提条件
- 能够访问您的 Plesk 面板(参见连接到 Plesk 界面)。
- 一个已绑定到您的托管空间并指向该空间的域名。
- 您的应用程序代码及其
package.json文件。 - 一种上传文件的方式:Plesk 文件管理器、FTP 账户或 Git 仓库。
- 如果您的应用程序使用 MySQL 或 MariaDB 数据库,还需要一个在 Plesk 中创建的数据库。
本指南使用 httpdocs,这是主域名通常使用的目录。附加域名的目录可能不同:请在 主机与 DNS > 主机 中查看 文档根目录。
了解运行原理
在 Plesk for Linux 上,您的应用程序不是通过 npm start 或 PM2 之类的进程管理器启动的,而是由应用服务器 Phusion Passenger 启动在 Plesk 中指定的文件,并将 Web 服务器收到的请求转发给它。
这带来三个实际影响:
- 端口由系统代为管理。 Passenger 会忽略传给
listen()的端口号,并自行接管您的 HTTP 服务器。您无需开放任何端口,也无需在网站地址中添加端口。 - 启动文件必须调用
listen(),可以直接调用,也可以通过加载执行该调用的文件来实现。 - 进程可能在空闲时停止,并在下一个请求到达时重新启动。因此,不要依赖内部定时器(
setInterval)执行周期性任务,请改用 Plesk 的 计划任务。
需要区分以下两个目录:
| Plesk 设置 | 作用 | 示例 |
|---|---|---|
| 应用程序根目录(Application Root) | 存放整个项目的目录:package.json、代码、node_modules |
/httpdocs |
| 文档根目录(Document Root) | 存放公开文件的子目录,由 Web 服务器直接提供 | /httpdocs/public |
文档根目录必须位于应用程序目录内部。只有其中的内容可以从 Web 直接访问:因此,只要不把 .env 文件、代码和 node_modules 放进 public,外部就无法访问它们。
步骤 1:准备应用程序
本指南使用以下目录结构:
httpdocs/
├── app.js
├── package.json
├── package-lock.json
└── public/
└── logo.png如果您想先验证配置,下面这个最简单的 app.js 文件不需要任何依赖项:
const http = require('node:http');
const server = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
res.end('Node.js 应用程序已上线\n');
});
server.listen(process.env.PORT || 3000);使用 Express 时,原理相同:
const express = require('express');
const app = express();
app.get('/', (req, res) => {
res.send('Node.js 应用程序已上线');
});
app.listen(process.env.PORT || 3000);保留 process.env.PORT || 3000,同一份代码也可以在您的本地计算机上运行。
同时请检查您的 package.json:其中列出了依赖项,而您要从 Plesk 运行的脚本必须写在 scripts 部分。
{
"name": "my-application",
"version": "1.0.0",
"private": true,
"main": "app.js",
"scripts": {
"build": "echo \"无需编译\""
},
"dependencies": {
"express": "^5.0.0"
}
}步骤 2:上传文件
将项目上传到 httpdocs,不要包含 node_modules 目录:依赖项将在步骤 4 中安装到服务器上。
首次上传最简单的方法如下:
- 在您的计算机上将项目打包为
.zip压缩文件。 - 在 Plesk 中打开 文件(文件管理器),然后进入
httpdocs目录。 - 上传该压缩文件。
- 勾选该文件,点击 提取文件,然后删除压缩文件。
- 如果
public目录不存在,请创建它:Plesk 需要用它作为文档根目录,即使该目录为空。
步骤 3:在 Plesk 中配置 Node.js
-
进入 网站与域名,找到您的域名。
-
点击 Node.js。如果该域名尚未配置网站,请依次点击 创建网站 > Node.js。
-
填写以下设置:
设置 应填写的值 Node.js 版本 您的应用程序要求的版本,或与开发环境最接近的版本 程序包管理器 npm或Yarn,视您的项目而定。Plesk 通常会给出正确的选择文档根目录 /httpdocs/public应用程序模式 网站准备就绪后使用 production,调试期间使用development。此值会写入NODE_ENV应用程序根目录 /httpdocs应用程序启动文件 app.js,或实际启动服务器的文件 -
如果界面提供 确定 按钮,请点击它进行确认。
步骤 4:启用应用程序并安装依赖项
仍在该域名的 Node.js 页面上:
- 点击 启用 Node.js。
- 点击 NPM 安装(或 Yarn 安装)。只有当
package.json位于应用程序目录中时,才会显示此按钮。 - 如果您的项目需要编译(TypeScript、前端等),请点击 运行脚本,输入脚本名称(例如
build),然后确认。 - 点击 重启应用 以加载最新版本。
步骤 5:设置环境变量
API 密钥、密码和其他敏感设置不应写在代码中。
- 在 Node.js 页面上,找到 自定义环境变量。
- 点击 指定,然后点击 添加变量。
- 输入名称和值,例如
DATABASE_HOST和localhost。 - 确认后点击 重启应用。
Node.js 不会自动加载 .env 文件。如果您的应用程序使用此类文件,需要由应用程序自行读取,例如借助 dotenv 包。
步骤 6:检查结果
在浏览器中打开 https://您的域名.com/。使用本指南的示例时,页面会显示 Node.js 应用程序已上线。
您也可以从自己的计算机检查响应:
curl -i https://您的域名.com/第一行应显示状态码 200。第一个请求可能较慢,因为应用程序需要时间启动。
要查看应用程序输出的消息,请从您的域名打开 日志,展开 所有日志,并只保留勾选 Node.js 一项。
更新应用程序
- 上传修改过的文件。
- 如果
package.json有变更,请再次点击 NPM 安装。 - 如有需要,重新运行编译脚本。
- 点击 重启应用。
要自动完成这些更新,请参阅使用 Plesk 从 GitHub 或 GitLab 部署。
故障排除
“Web application could not be started”或“We're sorry, but something went wrong”
应用程序在启动时崩溃。请打开 日志 查看确切的错误,然后检查:
- 应用程序根目录 中确实存在 应用程序启动文件;
- 依赖项已安装;
- Node.js 版本与项目要求的版本一致;
- 所有必需的环境变量均已设置。
Node.js 页面上显示“The file does not exist”
Plesk 找不到启动文件。请检查 应用程序根目录 和文件名,注意区分大小写。
Error: Cannot find module 'express'
缺少依赖项。请点击 NPM 安装,确认该模块列在 dependencies 中,而不只是列在 devDependencies 中,然后重启应用程序。
ERR_REQUIRE_ESM 或“require() of ES Module not supported”
Passenger 使用 require() 加载启动文件,如果您的项目使用 ES 模块(package.json 中设置了 "type": "module"),加载可能会失败。请在应用程序目录中创建一个简短的 passenger.cjs 文件:
import('./app.js').catch((error) => {
console.error(error);
process.exit(1);
});然后将 passenger.cjs 设为 应用程序启动文件,并重启应用程序。
应用程序无法启动并最终超时
启动文件很可能从未调用 listen()。这在使用 express-generator 创建的项目中很常见,此类项目由 bin/www 而不是 app.js 启动服务器。此时请指定正确的文件,或移动 listen() 调用。
与多个 HTTP 服务器相关的错误
Passenger 会接管第一个调用 listen() 的服务器;如果应用程序创建了多个服务器,则会报错。请明确指定要使用的服务器:
if (typeof PhusionPassenger !== 'undefined') {
PhusionPassenger.configure({ autoInstall: false });
}
const port = typeof PhusionPassenger !== 'undefined' ? 'passenger' : 3000;
server.listen(port);显示 Plesk 默认页面或 403 错误
请确认已为该域名启用 Node.js,并且 文档根目录 指向 /httpdocs/public。如果该目录中有旧的 index.html 文件,访问者看到的将是该文件而不是您的应用程序:请将其删除或重命名。
图片或样式表返回 404 错误
静态文件必须位于 文档根目录 中。URL /logo.png 对应文件 public/logo.png,地址中不包含 public。
您的修改没有生效
Node.js 会将代码保留在内存中。每次上传文件或更改变量后,请点击 重启应用。
NPM 安装 失败
请阅读显示的消息,其中会指出出现问题的包。检查 Node.js 版本 是否符合依赖项的 engines 字段,以及 package-lock.json 是否为最新。如果错误提到内存不足或原生模块编译,请通过您的客户区联系技术支持,并附上该消息。