立即开始
所有文章教程 · 3 分钟阅读

在 Rivervo 虚拟主机上部署 Node.js 应用(Next.js 和 Nuxt)。

RT
Rivervo Team · Rivervo
·
2026年4月29日
·
更新于 2026年11月13日
Node
ON SHARED HOSTING

很多人以为 Node.js 应用只能放在 VPS 上。其实不然——Rivervo 的每个虚拟主机套餐在网站菜单中都有 Node.js 和 Python,它会为您的应用启动一个 Phusion Passenger 进程,前端与您其他网站共用同一个 Apache。

本指南以两个最常用的框架 Next.js 和 Nuxt 3 为例,完整介绍整个流程。最终效果:您的应用运行在 https://nindeyuming.cn(或任意子域名)上,由真正的 Node.js 进程提供服务,重启后自动恢复,一键即可重启。

如果您从未在虚拟主机上部署过 Node 应用,大家最容易卡住的地方是启动文件——Passenger 需要一个入口脚本来启动您的框架。下面为每个框架都提供了一个,直接复制粘贴即可,无需修改。

开始之前需要准备

  • 一个 Rivervo 主机套餐(任何档次均可——所有套餐都支持 Node.js 应用)
  • 本地安装 Node.js v20 或更高版本,用于构建应用
  • 构建好的产物,准备上传(下面按框架分别介绍)
  • 账户的文件管理器或 SFTP 访问权限(两者均可)

您不需要 root、sudo、systemd 或反向代理配置。这些都由 Passenger 处理。

第 1 步:在本地构建应用

您要上传的是构建好的应用,而不是源代码。控制面板会安装依赖,但不会编译 React 或运行 Vite 构建。请先在您的电脑上完成这一步。

Next.js:

npm ci
npm run build

这会生成 .next/(构建输出)。此处不要运行 next start——稍后我们会通过启动文件来启动它。

Nuxt 3:

npm ci
npm run build

这会生成 .output/(Nuxt 的通用构建目录)。同样——暂时不要运行任何东西。

第 2 步:上传正确的文件

无需上传 node_modules/,控制面板会为您安装依赖。git 和构建缓存也不需要上传。

上传到您的账户,最好放在 public_html 之外的路径(例如 /home/<account>/myapp/)。为什么要放在外面?因为 Passenger 会自动把 public_html 挂载到网址根目录,把应用代码放在里面会将其暴露出去。

框架需要上传跳过
Next.js.next/、public/、package.json、package-lock.json、next.config.js、您的 server.cjs(见下文)node_modules/、.git/、.env.local
Nuxt 3.output/、package.json、package-lock.json、您的 server.cjs(见下文)node_modules/、.nuxt/、.git/、源码 pages/、components/

上传文件有两种方式:

  • 网站 → 文件 → 上传 zip 压缩包 → 解压,网络不稳定时这是最简单的方式。
  • SFTP(FileZilla、Cyberduck、rsync)在反复部署时更快。服务器、端口、用户名和密码见 网站 → SSH 和 SFTP。

第 3 步:添加启动文件

这是请求到达时 Passenger 执行的文件。把它放在应用文件夹中 package.json 的旁边。

Next.js:server.cjs

const next = require('next')
const http = require('http')
 
const port = process.env.PORT || 3000
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev, dir: __dirname })
const handle = app.getRequestHandler()
 
app.prepare().then(() => {
  http.createServer((req, res) => handle(req, res)).listen(port, () => {
    console.log(`Next.js server listening on port ${port}`)
  })
})

它的作用:

  • 加载 Next,并指向当前目录(即 .next/ 和 package.json 所在的目录)。
  • 基于 Next 的内部路由创建请求处理器。
  • 在 Passenger 分配的端口(process.env.PORT)上启动 HTTP 服务器。
  • 本地测试时回退到 3000 端口。

dev 根据 NODE_ENV 自动判断——在控制面板中设置 Production 模式(第 4 步中会做),Next 就会以生产模式运行。

Nuxt 3:server.cjs

import('./.output/server/index.mjs').then(({ createApp }) => {
  createApp().then(({ app }) => {
    const port = process.env.PORT || 3000
    app.listen(port, () => {
      console.log(`Nuxt server listening on port ${port}`)
    })
  })
})

它的作用:

  • 动态导入 Nuxt 的 .output/server/index.mjs(由 npm run build 生成的入口)。
  • 使用 createApp() 创建 H3 服务器实例。
  • 监听 Passenger 分配的端口。

这里有意使用动态 import()——.mjs 模块无法用 require() 加载,但 .cjs 文件可以动态导入它们。这是在 Passenger 启动器中最干净可行的写法。

第 4 步:在控制面板中创建应用

打开您的项目 → 网站 → Node.js 和 Python → Node.js application。

字段值
Version20 或更高
ModeProduction
Folder主目录下的 myapp(即您上传文件的位置)
地址nindeyuming.cn(或子域名,如 app.nindeyuming.cn)
Start fileserver.cjs

点击 创建。系统会在 ~/nodevenv/myapp/20/ 下创建 Node.js 环境。

安装依赖

应用创建后,点击其上的 Install dependencies (npm install) 并查看输出。如果失败:

  • 检查 package.json 是否位于应用根目录(而不是嵌套在子目录中)。
  • Next.js:确认 next 在 dependencies 中,而不是 devDependencies(生产环境安装会跳过开发依赖)。
  • Nuxt:nuxt 本身也应作为普通依赖。

添加环境变量

在应用的 设置 → Environment variables → Add a variable 中添加。Production 模式已经设置了 NODE_ENV=production。

对于在运行时读取配置(数据库地址、API 密钥)的 Next.js 应用,请在这里添加。不要上传含有密钥的 .env 文件——应用的环境变量才是正确的存放位置。

保存设置会重启应用,新变量立即生效。

第 5 步:验证

访问应用的网址,您应该能看到自己的应用。

如果看到 Passenger 错误页面,展开它并查看底部——几乎总有清晰的堆栈信息。最常见的两种:

Error: Cannot find module 'next'——npm install 没有运行,或在错误的文件夹中运行。再次点击 Install dependencies (npm install)。

Error: ENOENT: no such file or directory, open '.next/...'——您上传了源代码,但没有上传构建好的 .next/ 目录。请在本地构建后重新上传。

如何部署更新

重复第 1、2 步,然后点击应用上的 Restart。具体来说:

1. Build locally    npm run build
2. Upload          .next/ or .output/, plus any changed source/config
3. Panel          Restart the app

如果修改了 package.json,请在重启前点击 Install dependencies (npm install)。更喜欢命令行?在 网站 → 终端 中,应用卡片会显示进入其环境的命令。

常见问题

WebSocket: Passenger 支持 HTTP/1.1 和 HTTP/2。Next.js 和 Nuxt 内置路由的 WebSocket 升级可以正常工作。如果您使用单独的 WebSocket 服务器(ws、socket.io),它共用同一端口,并通过同一个 server.cjs 启动——无需额外配置。

文件上传 / next.config.js 中的 body-parser 限制: Passenger 默认的请求体大小上限为 10 MB。如果需要上传大文件,可以在 public_html 中通过 .htaccess 调高 passenger_max_request_size:

PassengerMaxRequestSize 52428800

(即 50 MB,以字节为单位。)

定时任务: 如果您的应用需要后台任务(发送电子报、定时导出),不要在 Web 进程中运行。使用 网站 → 定时任务 直接调用 Node 脚本:

/home/<account>/nodevenv/myapp/20/bin/node /home/<account>/myapp/scripts/send-newsletter.js

进程内存: 如果应用超出每个账户的内存上限(取决于您的套餐),Passenger 会重启应用。典型的 Next.js / Nuxt 应用空闲时占用不到 100 MB。如果您频繁触及上限,请先用 process.memoryUsage() 分析是否存在内存泄漏,再考虑是否需要更大的套餐。

自定义域名和 HTTPS: 您为应用设置的地址就是 Passenger 绑定的地址。SSL 自动配置——无需额外设置。如需使用其他域名或子域名,请先在 网站 → 域名 中添加,然后将其选为应用的地址。

Node 版本: Version 列表显示所有已安装的版本;可在应用的 设置 中切换。

什么情况下不适合用虚拟主机运行 Node

坦白说——虚拟主机上的 Node.js 非常适合作品集网站、博客、营销页面、小型 SaaS 前端和内部工具。但以下场景会比较吃力:

  • 高吞吐量的 API(持续超过 50 次请求/秒)——您会感受到每个账户的 CPU 上限
  • 有数千个并发连接的重度 WebSocket 应用
  • 需要派生工作进程的应用(队列处理、爬虫)——Passenger 对每个账户的进程数限制会让这类应用很别扭
  • 任何需要 systemd、Docker 或 root 权限的应用

这些场景请选择我们的 VPS——完整 root 权限、独立内核,想运行什么都可以。但对于大多数流量不算巨大的 Next.js 和 Nuxt 应用,本指南就足够了。

要点速览

  1. 在本地运行 npm run build
  2. 上传 .next/(Next)或 .output/(Nuxt)+ package.json + server.cjs
  3. 网站 → Node.js 和 Python → Node.js application → 选择文件夹,启动文件 server.cjs,模式 Production
  4. Install dependencies (npm install),然后 Restart

如果出现任何异常,请提交工单——贴上 Passenger 错误页面,我们会帮您定位到具体的代码行。

—— Rivervo 团队