中文

网站托管

在 Plesk 上部署 Node.js 应用程序

通过 Plesk 上线 Node.js 应用程序:目录结构、启动文件、npm 依赖项、环境变量、日志以及常见错误的解决方法。

阅读约 7 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

本指南介绍如何通过 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 文件不需要任何依赖项:

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 时,原理相同:

js
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 部分。

JSON
{
  "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 中安装到服务器上。

首次上传最简单的方法如下:

  1. 在您的计算机上将项目打包为 .zip 压缩文件。
  2. 在 Plesk 中打开 文件(文件管理器),然后进入 httpdocs 目录。
  3. 上传该压缩文件。
  4. 勾选该文件,点击 提取文件,然后删除压缩文件。
  5. 如果 public 目录不存在,请创建它:Plesk 需要用它作为文档根目录,即使该目录为空。

步骤 3:在 Plesk 中配置 Node.js

  1. 进入 网站与域名,找到您的域名。

  2. 点击 Node.js。如果该域名尚未配置网站,请依次点击 创建网站 > Node.js。

  3. 填写以下设置:

    设置 应填写的值
    Node.js 版本 您的应用程序要求的版本,或与开发环境最接近的版本
    程序包管理器 npm 或 Yarn,视您的项目而定。Plesk 通常会给出正确的选择
    文档根目录 /httpdocs/public
    应用程序模式 网站准备就绪后使用 production,调试期间使用 development。此值会写入 NODE_ENV
    应用程序根目录 /httpdocs
    应用程序启动文件 app.js,或实际启动服务器的文件
  4. 如果界面提供 确定 按钮,请点击它进行确认。

步骤 4:启用应用程序并安装依赖项

仍在该域名的 Node.js 页面上:

  1. 点击 启用 Node.js。
  2. 点击 NPM 安装(或 Yarn 安装)。只有当 package.json 位于应用程序目录中时,才会显示此按钮。
  3. 如果您的项目需要编译(TypeScript、前端等),请点击 运行脚本,输入脚本名称(例如 build),然后确认。
  4. 点击 重启应用 以加载最新版本。

步骤 5:设置环境变量

API 密钥、密码和其他敏感设置不应写在代码中。

  1. 在 Node.js 页面上,找到 自定义环境变量。
  2. 点击 指定,然后点击 添加变量。
  3. 输入名称和值,例如 DATABASE_HOST 和 localhost。
  4. 确认后点击 重启应用。

Node.js 不会自动加载 .env 文件。如果您的应用程序使用此类文件,需要由应用程序自行读取,例如借助 dotenv 包。

步骤 6:检查结果

在浏览器中打开 https://您的域名.com/。使用本指南的示例时,页面会显示 Node.js 应用程序已上线。

您也可以从自己的计算机检查响应:

终端
curl -i https://您的域名.com/

第一行应显示状态码 200。第一个请求可能较慢,因为应用程序需要时间启动。

要查看应用程序输出的消息,请从您的域名打开 日志,展开 所有日志,并只保留勾选 Node.js 一项。

更新应用程序

  1. 上传修改过的文件。
  2. 如果 package.json 有变更,请再次点击 NPM 安装。
  3. 如有需要,重新运行编译脚本。
  4. 点击 重启应用。

要自动完成这些更新,请参阅使用 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 文件:

js
import('./app.js').catch((error) => {
  console.error(error);
  process.exit(1);
});

然后将 passenger.cjs 设为 应用程序启动文件,并重启应用程序。

应用程序无法启动并最终超时

启动文件很可能从未调用 listen()。这在使用 express-generator 创建的项目中很常见,此类项目由 bin/www 而不是 app.js 启动服务器。此时请指定正确的文件,或移动 listen() 调用。

与多个 HTTP 服务器相关的错误

Passenger 会接管第一个调用 listen() 的服务器;如果应用程序创建了多个服务器,则会报错。请明确指定要使用的服务器:

js
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 是否为最新。如果错误提到内存不足或原生模块编译,请通过您的客户区联系技术支持,并附上该消息。