רבים מניחים שאפליקציות Node.js חייבות לרוץ על VPS. זה לא נכון — בכל חבילת אחסון משותף של Rivervo יש בתפריט האתר Node.js ו-Python, שמפעיל תהליך Phusion Passenger עבור האפליקציה שלכם מאחורי אותו Apache שמשרת את שאר האתרים.
המדריך עובר על כל התהליך בשתי המסגרות הנפוצות ביותר: Next.js ו-Nuxt 3. התוצאה: האפליקציה שלכם בכתובת https://hadomain.co.il (או בכל תת-דומיין), רצה על תהליך Node.js אמיתי, שורדת אתחולים וניתנת להפעלה מחדש בלחיצה אחת.
אם עוד לא פרסתם אפליקציית Node לאחסון משותף, החלק שבו כולם נתקעים הוא קובץ ההפעלה — Passenger צריך סקריפט כניסה אחד שמפעיל את המסגרת. נספק אחד לכל מסגרת בהמשך; העתיקו והדביקו, בלי שינויים.
מה צריך לפני שמתחילים
- חבילת אחסון של Rivervo (כל רמה — אפליקציות Node.js עובדות בכל החבילות)
- Node.js בגרסה 20 ומעלה במחשב המקומי, כדי לבנות את האפליקציה
- תוצר הבנייה, מוכן להעלאה (נפרט לכל מסגרת)
- גישה למנהל הקבצים או ל-SFTP של החשבון (שניהם עובדים)
לא צריך root, sudo, systemd או הגדרות reverse proxy. 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.
- מפעיל שרת HTTP על הפורט ש-Passenger מקצה (
process.env.PORT). - חוזר ל-
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}`)
})
})
})מה הוא עושה:
- מייבא באופן דינמי את
.output/server/index.mjsשל Nuxt (נקודת הכניסה ש-npm run buildיוצר). - משתמש ב-
createApp()כדי לבנות את מופע שרת ה-H3. - מאזין על הפורט ש-Passenger הקצה.
ה-import() הדינמי מכוון — אי אפשר לטעון מודולי .mjs עם require(), אבל קובץ .cjs יכול לייבא אותם דינמית. זו התבנית הנקייה ביותר שעובדת בתוך המפעיל של Passenger.
שלב 4 — יצירת האפליקציה בלוח הבקרה
פתחו את הפרויקט → אתר → Node.js ו-Python → אפליקציית Node.js.
| שדה | ערך |
|---|---|
| גרסה | 20 ומעלה |
| מצב | Production |
| תיקייה | myapp בתיקיית הבית (לשם העליתם את הקבצים) |
| כתובת | hadomain.co.il (או תת-דומיין כמו app.hadomain.co.il) |
| קובץ הפעלה | server.cjs |
לחצו יצירה. סביבת Node.js נוצרת תחת ~/nodevenv/myapp/20/.
התקנת תלויות
אחרי שהאפליקציה נוצרה, לחצו עליה התקנת תלויות (npm install) ועקבו אחרי הפלט. אם זה נכשל:
- ודאו ש-
package.jsonנמצא בשורש האפליקציה (ולא בתיקייה פנימית). - ב-Next.js: ודאו ש-
nextנמצא ב-dependenciesולא ב-devDependencies(התקנת ייצור מדלגת על תלויות פיתוח). - ב-Nuxt: גם
nuxtעצמו צריך להיות תלות רגילה.
הוספת משתני סביבה
הגדרות של האפליקציה → משתני סביבה → הוספת משתנה. מצב Production כבר מגדיר NODE_ENV=production.
באפליקציות Next.js שקוראות ערכים בזמן ריצה (כתובות מסד נתונים, מפתחות API), הוסיפו אותם כאן. אל תעלו קובץ .env עם סודות — משתני הסביבה של האפליקציה הם המקום הנכון.
שמירת ההגדרות מפעילה מחדש את האפליקציה, כך שהמשתנים החדשים חלים מיד.
שלב 5 — אימות
היכנסו לכתובת האפליקציה. אתם אמורים לראות את האפליקציה שלכם.
אם מופיע דף שגיאה של Passenger, הרחיבו אותו והסתכלו בתחתית — כמעט תמיד יש שם stack trace ברור. שתי הנפוצות:
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) לפני ההפעלה מחדש. מעדיפים שורת פקודה? אתר → טרמינל: כרטיס האפליקציה מציג את הפקודה לכניסה לסביבה שלה.
מלכודות נפוצות
WebSockets: Passenger מטפל ב-HTTP/1.1 וב-HTTP/2. שדרוג ל-WebSocket עובד בנתיבים המובנים של Next.js ו-Nuxt. אם אתם משתמשים בשרת WebSocket נפרד (ws, socket.io), הוא חולק את אותו פורט ועולה דרך אותו server.cjs — בלי הגדרות נוספות.
העלאת קבצים / מגבלות body-parser ב-next.config.js: מגבלת גוף הבקשה ברירת המחדל של Passenger היא 10 MB. אם מעלים קבצים גדולים, הגדירו passenger_max_request_size גבוה יותר דרך .htaccess ב-public_html:
PassengerMaxRequestSize 52428800(50 MB בבתים.)
משימות Cron: אם האפליקציה צריכה משימות רקע (שליחת ניוזלטרים, ייצואים מתוזמנים), אל תריצו אותן בתוך תהליך הווב. השתמשו ב-אתר → משימות Cron כדי להפעיל סקריפט Node ישירות:
/home/<account>/nodevenv/myapp/20/bin/node /home/<account>/myapp/scripts/send-newsletter.jsזיכרון התהליך: Passenger מפעיל מחדש את האפליקציה אם היא חורגת ממגבלת ה-RAM של החשבון (תלוי בחבילה). אפליקציית Next.js / Nuxt טיפוסית צורכת במנוחה פחות מ-100 MB. אם אתם מגיעים למגבלות, עשו פרופיילינג עם process.memoryUsage() וחפשו דליפות לפני שתניחו שצריך חבילה גדולה יותר.
דומיינים מותאמים ו-HTTPS: הכתובת שהגדרתם לאפליקציה היא מה ש-Passenger מאזין לו. SSL אוטומטי — בלי הגדרות נוספות. לדומיין אחר או לתת-דומיין, הוסיפו אותו קודם תחת אתר → דומיינים, ואז בחרו אותו ככתובת האפליקציה.
גרסת Node: הרשימה גרסה מציגה כל גרסה מותקנת; מחליפים אותה ב-הגדרות של האפליקציה.
מתי לא להשתמש באחסון משותף ל-Node
בכנות — Node.js באחסון משותף עובד מצוין לאתרי תיק עבודות, בלוגים, דפי שיווק, ממשקי SaaS קטנים וכלים פנימיים. הוא מתקשה עם:
- ממשקי API עם תפוקה גבוהה (יותר מ-50 בקשות בשנייה לאורך זמן) — תרגישו את מגבלת ה-CPU לחשבון
- אפליקציות עמוסות WebSocket עם אלפי חיבורים במקביל
- אפליקציות שמפצלות תהליכי עבודה (queue workers, scrapers) — מכסת התהליכים לחשבון של 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