TL;DR: כשהדפלוי ל-Vercel נכשל, אל תנחשו. פתחו את לוג ה-Build של הדפלוי הספציפי, גללו לשורת השגיאה הראשונה (לא האחרונה), וזהו לאיזו מהחמש הקטגוריות היא שייכת: משתני סביבה חסרים, imports רגישי אותיות (עבד מקומית, נשבר ב-CI), גרסת Node לא תואמת, נגמר הזיכרון, או תיקיית פלט שגויה. ברוב המקרים התיקון הוא שינוי הגדרה אחת או שורת קוד אחת. המדריך הזה עובר על כל אחת מהן לפי סדר שכיחות, עם הפקודות המדויקות.
מה רואים על המסך
התופעה: הדפלוי ל-Vercel מסתיים בכשל, ובראש הדשבורד מופיע "Deployment failed" או "Error" עם רקע אדום, במקום "Ready" ירוק.
הסימנים המוכרים:
- הודעה כללית בסגנון
Error: Command "npm run build" exited with 1. - הדף שהיה חי עד לפני רגע ממשיך להציג את הגרסה הישנה (Vercel לא מקדם דפלוי שנכשל, וזה דבר טוב).
- לפעמים הבנייה עצמה מצליחה אבל הדף מציג מסך לבן או שגיאת 404, וזה סוג אחר של תקלה שנגיע אליה בסעיף תיקיית הפלט.
- המצב המתסכל ביותר:
npm run buildרץ מצוין אצלכם במחשב, אבל אותו קוד בדיוק נכשל ב-Vercel.
הנקודה הכי חשובה להבנה: Vercel לא "שובר" את הקוד שלכם. הוא מריץ אותו בסביבה נקייה, על שרת לינוקס, בלי ה-cache המקומי שלכם ובלי הקבצים שלא נכנסו ל-git. כמעט תמיד השגיאה הייתה קיימת גם אצלכם, רק שהסביבה המקומית הסתירה אותה.
למה זה קורה
רוב כשלי הדפלוי ב-Vercel נובעים מהבדל בין הסביבה המקומית לסביבת ה-CI, ולא מבאג בלוגיקה. חמש סיבות מכסות את הרוב המוחלט של המקרים, לפי סדר שכיחות.
-
משתני סביבה חסרים ב-Vercel. הקובץ
.envשלכם קיים מקומית אבל לא נכנס ל-git (וזה נכון שהוא לא נכנס). Vercel לא מכיר אותו, ולכןprocess.env.VITE_SUPABASE_URLמקבלundefined, והבנייה או ה-runtime נופלים. זו הסיבה הנפוצה ביותר. -
עבד מקומית, נכשל ב-CI, imports רגישי אותיות. macOS ו-Windows לא מבחינים בין אותיות גדולות לקטנות בשמות קבצים. לינוקס, שעליו רץ Vercel, כן. אם ייבאתם
import Header from './components/header'אבל הקובץ נקראHeader.tsx, זה יעבוד מצוין במק ויתפוצץ ב-Vercel עםModule not found. -
גרסת Node לא תואמת. מקומית אתם על Node 20, אבל Vercel ברירת המחדל עשוי להריץ גרסה אחרת. חבילות מסוימות דורשות גרסה מינימלית, ותכונות שפה חדשות פשוט לא קיימות בגרסה ישנה יותר.
-
נגמר הזיכרון (Out of Memory). פרויקטים גדולים, במיוחד עם המון dependencies או source maps כבדים, חוצים את תקרת הזיכרון של סביבת הבנייה. השגיאה נראית כמו
JavaScript heap out of memoryאו שהתהליך נהרג בשקט עם קוד יציאה 137. -
תיקיית פלט שגויה או שגיאות TypeScript שחוסמות בנייה. אם Vercel מחפש את הפלט ב-
distאבל הכלי שלכם כותב ל-build(או להפך), תקבלו דף ריק. ובנפרד: שגיאת TypeScript אחת קטנה, שמקומית היא רק קו אדום מתחת לקוד, יכולה להפיל את כל הבנייה ב-CI כיtscמחזיר קוד יציאה שאינו אפס.
הרבה מהמקרים האלה הם סימפטום של חוב טכני שהצטבר בפרויקט שנבנה מהר, ושל קוד שנוצר על ידי כלי Vibe Coding שעבד בסביבת הפיתוח אבל מעולם לא נבדק בסביבת ייצור אמיתית.
איך מתקנים
התהליך תמיד מתחיל בקריאת הלוג, לא בניחוש. פתחו את הדפלוי שנכשל, קראו את שורת השגיאה הראשונה, ורק אז פנו לתיקון המתאים.
שלב 0: קראו את לוג ה-Build (חובה, לפני כל תיקון)
- בדשבורד של Vercel, כנסו לפרויקט ולחצו על הדפלוי האדום שנכשל.
- פתחו את הסקשן Building ולחצו להרחבה מלאה.
- גללו למעלה עד לשורת השגיאה הראשונה. זו הטעות הכי נפוצה: אנשים קוראים את השורות האחרונות, שהן בדרך כלל רק "התהליך נכשל", במקום את השורה הראשונה שמסבירה למה.
חפשו מילות מפתח: Module not found, undefined, heap out of memory, Type error, command not found, ENOENT.
תיקון 1: הגדרת משתני סביבה
אם הלוג מזכיר משתנה שהוא undefined או שגיאה שקשורה לחיבור למסד נתונים או API:
- ב-Vercel: Settings → Environment Variables.
- הוסיפו כל משתנה שקיים ב-
.envהמקומי שלכם. שימו לב לתחילית הנכונה: ב-Vite חייביםVITE_לכל משתנה שמגיע לצד הלקוח. - בחרו את הסביבות הנכונות (Production, Preview, Development).
- חשוב: משתני סביבה חדשים נכנסים לתוקף רק בדפלוי הבא. הפעילו Redeploy ידני, ואל תסמנו "Use existing Build Cache".
בדיקה מקומית מהירה שהמשתנים באמת קיימים:
# רשימת המשתנים שהקוד מצפה להם
grep -rE "import\.meta\.env\.|process\.env\." src/ | grep -oE "(VITE_|NEXT_PUBLIC_)[A-Z_]+" | sort -u
השוו את הפלט לרשימה ב-Vercel. כל משתנה חסר הוא דפלוי שנכשל.
תיקון 2: imports רגישי אותיות
אם הלוג אומר Module not found: Can't resolve './components/header' אבל הקובץ קיים אצלכם:
- השוו אות-באות בין ה-import לשם הקובץ בפועל, כולל תיקיות ביניים.
- תקנו את ה-import שיתאים בדיוק לשם הקובץ.
- איתור אוטומטי של ההפרש בין מה ש-git שומר לבין מה שקיים בדיסק:
# מציג קבצים ש-git מכיר בשם שונה מזה שבדיסק (בעיית case)
git ls-files | while read f; do [ -e "$f" ] || echo "case mismatch: $f"; done
מניעה לטווח ארוך: הגדירו את git שיתפוס שינויי case, וב-Windows/macOS הפעילו את ה-linter של imports.
git config core.ignorecase false
תיקון 3: התאמת גרסת Node
אם הלוג מזכיר תחביר לא מזוהה, Unsupported engine, או תכונה שלא קיימת:
- בדקו על איזו גרסה אתם רצים מקומית:
node -v. - נעלו את אותה גרסה בקובץ
package.json:
{
"engines": {
"node": "20.x"
}
}
- בנוסף, ב-Vercel: Settings → General → Node.js Version, בחרו את אותה גרסה מרכזית.
- עשו commit ו-Redeploy. עכשיו הסביבה המקומית וה-CI מדברות באותה שפה.
תיקון 4: נגמר הזיכרון
אם ראיתם JavaScript heap out of memory או קוד יציאה 137:
- העלו את תקרת הזיכרון של Node בסקריפט הבנייה:
{
"scripts": {
"build": "NODE_OPTIONS=--max-old-space-size=4096 vite build"
}
}
- צמצמו את מה שגורם לנפח: כבו source maps בפרודקשן אם אינכם צריכים אותם, ובדקו אם יש חבילה כבדה שנכנסת ל-bundle ואפשר לטעון אותה בעצלתיים (lazy).
- אם זה נמשך, זה סימן לבעיה מבנית עמוקה יותר בגודל ה-bundle, ולא רק לטריק של דגל זיכרון.
תיקון 5: תיקיית פלט ושגיאות TypeScript
אם הבנייה מצליחה אבל הדף ריק, או שהלוג מראה Type error:
- תיקיית פלט: ב-Vercel Settings → Build & Output Settings, ודאו ש-Output Directory תואם למה שהכלי שלכם באמת כותב (
distל-Vite,.nextל-Next.js,buildל-Create React App). - שגיאות TypeScript: מקומית שרת הפיתוח מתעלם מהן, אבל
tscבבנייה מחזיר קוד שגיאה. הריצו את אותה בדיקה שה-CI מריץ, מקומית, לפני שאתם דוחפים:
# מריץ בדיוק את מה ש-Vercel יריץ, בלי cache
rm -rf dist && npm run build
אם זה נכשל אצלכם, זה יכשל גם ב-Vercel. תקנו את שגיאות הטיפוסים עד שהפקודה עוברת נקי, ואז דחפו.
איך למנוע את זה בפעם הבאה
מרבית כשלי הדפלוי נמנעים אם מריצים מקומית את אותה בנייה נקייה שה-CI מריץ, לפני כל push.
- הריצו בנייה נקייה לפני push:
rm -rf dist node_modules && npm ci && npm run build. אם זה עובר על מכונה נקייה, סביר מאוד שיעבור גם ב-Vercel. - נעלו את גרסת ה-Node ב-
enginesוב-.nvmrcכדי שכל הסביבות זהות. - תעדו את משתני הסביבה: החזיקו
.env.exampleמעודכן ב-git עם שמות המשתנים (בלי הערכים), כך שאף אחד לא ישכח להוסיף משתנה חדש ל-Vercel. - בדקו את הבנייה מול Preview Deployments: כל Pull Request ב-Vercel מקבל דפלוי Preview. בדקו אותו לפני מיזוג ל-main, כדי שהפרודקשן לא יהיה המקום הראשון שבו אתם מגלים תקלה.
- הפעילו linter שתופס imports רגישי אותיות כדי שהבעיה תיתפס במחשב ולא ב-CI.
מתי זה יותר מתיקון מהיר
אם תיקנתם את משתני הסביבה ואת ה-imports וה-Node, אבל הדפלוי ממשיך להיכשל בדרכים חדשות בכל פעם, אתם כבר לא מתמודדים עם באג בודד אלא עם צנרת דפלוי לא יציבה.
הסימנים שהבעיה עמוקה יותר:
- כל דפלוי נכשל מסיבה אחרת, ואתם מטליאים סימפטומים בלי סוף.
- הבנייה עוברת לפעמים ונכשלת לפעמים על אותו קוד בדיוק (בעיות תזמון, race conditions, או תלות בשירות חיצוני לא יציב).
- אתם מפחדים לדחוף ל-main כי אף אחד לא באמת יודע מה ישבור את הפרודקשן.
- הפרויקט נבנה במהירות עם כלי AI, עובד יפה בסביבת הפיתוח, אבל אף פעם לא עבר הקשחה לקראת ייצור. זה בדיוק התרחיש של סוכן AI ששבר את הפרודקשן, או של פרויקט Lovable/Base44 שקורס.
במצבים כאלה, הפתרון הוא לא עוד דגל בקובץ ה-build, אלא ביקורת מסודרת של מוכנות הפרויקט לייצור: תצורת הבנייה, ניהול הסודות, גרסאות, וצנרת ה-CI/CD כמכלול אחד. זה בדיוק מה שאנחנו ב-VibeScale עושים: חילוץ פרויקטים שנבנו מהר וייצוב שלהם לסביבת ייצור אמיתית, בלי לכתוב הכל מחדש.
אם אתם תקועים ומעדיפים שמישהו ינתח את הצנרת שלכם לעומק, התחילו עם ביקורת מוכנות לייצור או קראו על שירות החילוץ שלנו. וכשאתם צריכים מבט מהיר על מה ששבור בדפלוי שלכם ממש עכשיו, דברו איתנו בוואטסאפ ונעזור לכם לזהות את הסיבה השורשית.
