很多人以為 Node.js 應用程式一定要放在 VPS 上。其實不然——Rivervo 的每個虛擬主機方案,網站選單中都有 Node.js 與 Python,會在服務您其他網站的同一個 Apache 前端後方,為您的應用程式啟動一個 Phusion Passenger 程序。
本指南以最常見的兩個框架 Next.js 和 Nuxt 3 走完整個流程。最終成果:您的應用程式在 https://yourshop.tw(或任何子網域)上執行,由真正的 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/<帳號>/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 應用程式。
| 欄位 | 值 |
|---|---|
| 版本 | 20 或更新版本 |
| 模式 | Production |
| 資料夾 | 家目錄中的 myapp(您上傳檔案的位置) |
| 網址 | yourshop.tw(或子網域,例如 app.yourshop.tw) |
| 啟動檔 | server.cjs |
按一下 建立。系統會在 ~/nodevenv/myapp/20/ 下建立 Node.js 環境。
安裝相依套件
應用程式建立後,按一下其上的 安裝相依套件(npm install),並觀察輸出。如果失敗:
- 確認
package.json位於應用程式根目錄(而非巢狀目錄中)。 - Next.js:確認
next在dependencies中,而不是devDependencies(正式安裝會略過開發用相依套件)。 - Nuxt:
nuxt本身也應該是一般相依套件。
新增環境變數
在應用程式的 設定 → 環境變數 → 新增變數。Production 模式已經會設定 NODE_ENV=production。
對於在執行時讀取設定的 Next.js 應用程式(資料庫網址、API 金鑰),請在這裡新增。不要隨程式碼一起上傳含有機密資訊的 .env 檔案——應用程式的環境變數才是正確的位置。
儲存設定會重新啟動應用程式,新的變數會立即生效。
步驟 5——驗證
開啟您的應用程式網址,應該就能看到您的應用程式。
如果看到 Passenger 錯誤頁面,展開它並看最下方——幾乎都會有清楚的堆疊追蹤。最常見的兩種:
Error: Cannot find module 'next'——npm install 沒有執行,或在錯誤的資料夾中執行。再按一次 安裝相依套件(npm install)。
Error: ENOENT: no such file or directory, open '.next/...'——您上傳了原始碼,卻沒有上傳建置後的 .next/ 目錄。請在本機建置後重新上傳。
如何部署更新
重複步驟 1、2,然後在應用程式上按一下 重新啟動。具體來說:
1. 本機建置 npm run build
2. 上傳 .next/ 或 .output/,以及有變更的原始碼/設定
3. 控制台 重新啟動應用程式如果您變更了 package.json,重新啟動前請先按 安裝相依套件(npm install)。偏好使用命令列?網站 → 終端機:應用程式卡片上會顯示進入其環境的指令。
常見陷阱
WebSocket: Passenger 支援 HTTP/1.1 和 HTTP/2。WebSocket 升級可用於 Next.js 和 Nuxt 的內建路由。如果您使用獨立的 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。)
排程工作: 如果您的應用程式需要背景工作(寄送電子報、定期匯出),不要在網頁程序中執行。請使用 網站 → 排程工作 直接呼叫 Node 腳本:
/home/<帳號>/nodevenv/myapp/20/bin/node /home/<帳號>/myapp/scripts/send-newsletter.js程序記憶體: 如果應用程式超過每個帳號的 RAM 上限(依方案而定),Passenger 會將它重新啟動。一般的 Next.js/Nuxt 應用程式閒置時低於 100 MB。如果您碰到上限,請先用 process.memoryUsage() 分析並找出記憶體洩漏,再考慮是否需要更大的方案。
自訂網域與 HTTPS: 您為應用程式設定的網址就是 Passenger 綁定的位址。SSL 自動啟用,不需要額外設定。若要使用其他網域或子網域,請先在 網站 → 網域 中新增,再將它選為應用程式的網址。
Node 版本: 版本 清單會列出所有已安裝的版本;可在應用程式的 設定 中切換。
什麼時候不該用虛擬主機跑 Node
坦白說——虛擬主機上的 Node.js 非常適合作品集網站、部落格、行銷頁面、小型 SaaS 前端、內部工具。但以下情況就比較吃力:
- 高吞吐量的 API(持續每秒超過 50 個請求)——您會感受到每個帳號的 CPU 上限
- 需要數千個同時連線的大量 WebSocket 應用程式
- 會分叉出工作程序的應用程式(佇列工作程序、爬蟲)——Passenger 對每個帳號的程序數量限制會讓這件事很彆扭
- 任何需要 systemd、Docker 或 root 權限的東西
這些情況請選擇我們的 VPS——完整 root 權限、獨立核心,想跑什麼都可以。但對於多數流量不算龐大的 Next.js 和 Nuxt 應用程式,這篇指南就是您需要的全部。
重點摘要
- 在本機執行
npm run build - 上傳
.next/(Next)或.output/(Nuxt)+package.json+server.cjs - 網站 → Node.js 與 Python → Node.js 應用程式 → 選擇資料夾,啟動檔
server.cjs,模式 Production - 安裝相依套件(npm install),然後 重新啟動
如果有任何異常,請開一張工單——貼上 Passenger 錯誤頁面,我們會幫您指出問題所在的那一行。
— Rivervo 團隊