Vercel: משתני סביבה בלי ‎.env ב-Git

המדריך הזה מיועד לפרויקט שכבר מתארח ב-Vercel. נדרשת לכם גישה להגדרות שלו והבנה אילו משתנים האפליקציה קוראת. הדוגמה שלהלן מתאימה ל-Next.js; אי אפשר להעביר אוטומטית שמות משתנים ממסגרת עבודה אחרת. המדריך מבוסס על תיעוד רשמי; הוא לא נבדק בחשבון אמיתי.

מידע מעשי על השימוש ב-Ailoot זמין בתיעוד.

למה אין צורך להוסיף את ‎.env ל-Git#

משתנה סביבה הוא הגדרה עם שם וערך שהאפליקציה מקבלת בנפרד מקוד המקור שלה. לדוגמה, השם SERVICE_API_KEY מאפשר לתוכנית לגשת לערך של מפתח בשירות חיצוני. אל תכניסו את המפתח עצמו למדריך, לשיחה עם סוכן או למאגר.

Next.js יכולה לטעון משתנים מקובצי .env* מקומיים. עם זאת, קובץ מקומי והגדרות הפרויקט ב-Vercel הם שני מיקומים נפרדים. אם הקובץ לא הועלה למאגר, הגדירו את הערכים בנפרד בפלטפורמת האירוח. התבנית הסטנדרטית של create-next-app מוסיפה קובצי .env ל-.gitignore; תיעוד Next.js מזהיר שכמעט לעולם אין להעלות אותם למאגר.

אם עדיין לא ברור לכם מה אפשר לשמור בקובצי המקור, התחילו בבדיקת האבטחה לפרויקט שנבנה בעזרת AI. כאן אנחנו עוסקים בשאלה מצומצמת יותר: היכן להגדיר את התצורה לפריסת Vercel מסוימת.

תחילה, בררו היכן האפליקציה קוראת את המשתנה#

לפני הזנת ערכים, הכינו רשימה של שמות, בלי הסודות עצמם. לכל שם עליכם לברר שלושה דברים: באיזו סביבה משתמשים בו, היכן רץ הקוד שקורא את המשתנה, ומתי נדרש הערך.

סביבת Development מיועדת לפיתוח מקומי. Preview מיועדת לפריסות תצוגה מקדימה, ו-Production מיועדת לגרסה הראשית שפורסמה. ל-Preview יכולות להיות הגדרות עבור ענף Git מסוים: הגדרות אלה גוברות על הגדרות Preview הכלליות בעלות אותם שמות.

בפרויקט Next.js, משתנים ללא NEXT_PUBLIC_ זמינים בשרת כברירת מחדל. הקידומת NEXT_PUBLIC_ מאפשרת להטמיע את הערך ב-JavaScript שנשלח לדפדפן. הדבר מתאים להגדרה שהיא ציבורית במפורש, כגון תווית גרסה שאינה סודית, אך לא למפתח API פרטי. גם ללא הקידומת הזאת, אסור לקוד האפליקציה להחזיר סוד ללקוח באופן ידני.

אם עדיין לא זיהיתם את מסגרת העבודה, בקשו מהסוכן לזהות אותה לפי קובצי הפרויקט. ההשוואה בין Astro ל-Next.js יכולה לעזור לכם להבין את ההבדלים; אי אפשר להחיל את כלל NEXT_PUBLIC_ על כל אפליקציית React.

הגדרת אירוח היא אחת המשימות הכרוכות בעבודה על אפליקציה עם סוכן AI.

איך להוסיף משתנה לפרויקט Vercel#

בצעו בעצמכם את השלבים בלוח הבקרה הרשמי. אל תמסרו לסוכן מפתח אמיתי כדי שימלא את הטופס, ואל תצרפו צילום מסך שמופיע בו הערך.

1. פתחו את לוח הבקרה של Vercel ובחרו את הפרויקט הנכון. אל תסתמכו רק על שם מאגר תואם: בדקו שאתם מגדירים את האפליקציה שאתם מתכוונים לפתוח.
2. עברו אל Environment Variables בסרגל הצד של הגדרות הפרויקט.
3. בשדה Name, הזינו את השם שהאפליקציה קוראת, כגון SERVICE_API_KEY. זהו שם לדוגמה; אם הקוד מצפה לשם אחר, השתמשו באיות המדויק שלו.
4. בשדה Value, הזינו את הערך ממאגר האישורים שלכם. אל תשימו אותו בקוד המקור, בצ'אט או ביומן אימות.
5. בחרו את הסביבה שזקוקה להגדרה הזאת. השתמשו ב-Preview כדי לבדוק גרסת תצוגה מקדימה וב-Production לגרסה הראשית. אל תקצו באופן אוטומטי סוד אחד לכל הסביבות.
6. אם הגדרת Preview חלה על ענף מסוים, בדקו את הענף שנבחר ואת כל הגדרה עוקפת בעלת אותו שם.
7. לחצו על Save.

Vercel מעמידה משתני פרויקט לרשותכם גם בזמן הבנייה וגם בעת הפעלת Vercel Functions בצד השרת. עם זאת, העובדה שערך זמין בתוך Vercel אינה אומרת שאפשר לשלוח אותו לדפדפן: הדבר תלוי בקוד האפליקציה ובכללי מסגרת העבודה.

למה צריך פריסה חדשה אחרי Save#

שמירת משתנה אינה משנה פריסות קיימות. תיעוד Vercel מחייב לפרוס מחדש את הפרויקט כדי שההגדרה החדשה תגיע לגרסה שבה אתם משתמשים.

כשעובדים דרך Git, אפשר ליצור פריסת Production חדשה על ידי דחיפת commit לענף שצוין ב-Production Branch, ופריסת Preview על ידי דחיפה לענף אחר. אל תניחו שהענף הראשי הוא תמיד main: בדקו את ההגדרה בפרויקט שלכם. זו צריכה להיות מהדורת פרויקט רגילה ומוסכמת, בלי להוסיף לקובץ commit קובץ סודות.

אחרי התחלת הפריסה, המתינו לסיום הבנייה ופתחו את כתובת ה-URL של הפריסה החדשה. שמרו רישום של כתובת ה-URL, הסביבה והענף שלה. אם תבדקו את כתובת ה-URL הישנה של פריסה מסוימת, ההגדרות החדשות לא יופיעו בה.

ל-Next.js יש תנאי נוסף: הפניות כגון process.env.NEXT_PUBLIC_RELEASE_LABEL מוחלפות בערכים שלהן במהלך next build. הערך נקבע לאחר הבנייה. שינוי ההגדרה בלי בנייה חדשה לא יחליף את ה-JavaScript שכבר נשלח לדפדפן.

איך לבדוק את התוצאה בלי לחשוף את המפתח#

התחילו בדוגמה בטוחה: תווית מפורשת שאינה סודית בשם NEXT_PUBLIC_RELEASE_LABEL עם הערך preview-check. אלה שם וטקסט לדוגמה, לא מפתח או בדיקה שבוצעה כאן. אם אפליקציית Next.js קוראת את המשתנה ישירות דרך process.env.NEXT_PUBLIC_RELEASE_LABEL, היא יכולה להציג את התווית במקום המיועד בממשק לאחר בנייה חדשה. בדיקה זו רק מאשרת שההגדרה הציבורית הועברה.

מפתח פרטי בודקים בדרך אחרת. אל תציגו את הערך שלו, חלק ממנו, את אורכו או את כל process.env. אל תיצרו כתובת ציבורית שמחזירה את תוכן המשתנה. תחילה בדקו רק אם ההגדרה “קיימת / לא קיימת” בשרת, ואז בדקו בנפרד את פונקציית האפליקציה שמשתמשת בשירות. עצם קיומה של הגדרה אינו מוכיח שהמפתח תקף או שיש לו את ההרשאות הנדרשות.

אפשר לתעד את התוצאות בלי סודות:

• הפרויקט, הסביבה והענף תואמים לאלה שנבחרו בזמן ההגדרה;
• אתם בודקים את כתובת ה-URL של פריסה חדשה שנוצרה לאחר שמירת המשתנה;
• הבנייה הסתיימה ופונקציית האפליקציה הנדרשת רצה על נתוני בדיקה בטוחים;
• הסוד אינו חשוף בדפדפן, בתגובות API, ביומנים או בשיחות.

אם הפונקציה מבצעת תשלום, שולחת הודעה או מבצעת פעולה אחרת שיש לה השלכות, השתמשו במצב הבדיקה הייעודי של השירות. בדיקת התצורה כשלעצמה אינה מאשרת פעולה אמיתית.

מה לבדוק אם הערך עדיין undefined#

undefined פירושו שלא התקבל ערך בנקודת הגישה הזאת. עברו לפי הסדר על השם, הסביבה והגרסה, בלי לשנות את כל ההגדרות בבת אחת.

לאחר שבדקתם את השם, הסביבה והגרסה החדשה, שגיאה בפונקציה עדיין אינה מוכיחה שהמשתנה גרם לה. בדקו את שגיאת הקוד הספציפית בצד השרת בלי לפרסם נתוני אבחון שמכילים סודות. המדריך הזה אינו מבטיח לפתור כל תגובת HTTP 500.

מעבר לשרת משלכם דורש הליך אחר: ראו את המדריך לפריסת פרויקט עם Coolify. שמות הכפתורים ושלבי התצורה של Vercel אינם חלים עליו.

עברו אל Ailoot.