$ man how-to/env-files-explained

קובץ .env הוא קובץ טקסט פשוט שמאחסן ערכי קונפיגורציה שהאפליקציה שלך צריכה כדי לרוץ. מפתחות API, סיסמאות מסד נתונים, כתובות URL של שירותים, דגלי פיצ'רים. זוג מפתח-ערך אחד בכל שורה. לא צריך גרשיים (אבל חלק מהפרסרים מקבלים אותם). בלי תחביר מיוחד. הקובץ יושב בתיקיית השורש של הפרויקט ולעולם לא מתקבל ב-Git. הקוד שלך קורא ממנו באמצעות process.env.VARIABLE_NAME ב-Node.js או os.environ ב-Python. הערכים קיימים רק על המחשב שלך. לחבר לצוות יש .env משלו עם המפתחות שלו. לסביבת הייצור יש סט משלה על פלטפורמת האירוח. השם מתחיל בנקודה, מה שהופך אותו לקובץ מוסתר ב-Mac ו-Linux. זה מכוון. הוא לא אמור להיות גלוי כברירת מחדל כי הוא מכיל סודות.

PATTERN

שלוש בעיות שקבצי .env פותרים. ראשית, אבטחה. מפתחות API שמקודדים קשיח בקבצי מקור מגיעים ל-GitHub. בוטים סורקים ריפוים ציבוריים לחיפוש מפתחות חשופים תוך דקות מ-push. מפתחות AWS נגנבים. מפתחות Stripe נגנבים. זה קורה כל הזמן. קבצי .env שומרים סודות מחוץ לבקרת גרסאות לחלוטין. שנית, ניידות. המחשב המקומי שלך, שרת ה-staging שלך, ושרת הייצור שלך כולם צריכים כתובות URL שונות למסד נתונים, endpoints שונים ל-API, דגלי פיצ'רים שונים. אותו codebase, משתני סביבה שונים. פורסים את אותו קוד בכל מקום וקובץ ה-.env אומר לו איך להתנהג. שלישית, שיתוף פעולה. חבר לצוות משתמש במפתחות API שלו. צינור ה-CI שלך משתמש במפתחות חשבון שירות. אף אחד לא משתף credentials דרך Slack או אימייל. לכל אחד יש קובץ .env משלו עם הערכים שלו.

CODE

שלב 1: צור את הקובץ בתיקיית השורש של הפרויקט. touch .env שלב 2: הוסף את המשתנים שלך. אחד בכל שורה. בלי רווחים סביב סימן השוויון. API_KEY=sk_live_abc123 DATABASE_URL=postgres://user:pass@localhost:5432/mydb NEXT_PUBLIC_SITE_URL=http://localhost:3000 DEBUG=true שלב 3: הוסף .env ל-.gitignore שלך מיד. זה לא ניתן למשא ומתן. echo ".env" >> .gitignore echo ".env.local" >> .gitignore echo ".env*.local" >> .gitignore שלב 4: התקן loader אם לפריימוורק שלך אין אחד מובנה. Next.js טוען קבצי .env אוטומטית. לפרויקטי Node.js אחרים, השתמש ב-dotenv: npm install dotenv אז בראש קובץ הכניסה שלך: require('dotenv').config() שלב 5: גישה למשתנים בקוד שלך. Node.js: process.env.API_KEY Python: os.environ.get('API_KEY') Next.js (צד לקוח): process.env.NEXT_PUBLIC_SITE_URL הקידומת NEXT_PUBLIC_ ב-Next.js אומרת שהמשתנה חשוף לדפדפן. בלי הקידומת הזו, הוא נשאר בצד השרת בלבד. זה חשוב. אל תשים מפתחות סודיים מאחורי NEXT_PUBLIC_.

PATTERN

רוב הפריימוורקים תומכים במספר קבצי .env עם סדר עדיפויות טעינה. Next.js טוען אותם בסדר הזה, כאשר קבצים מאוחרים דורסים קודמים: .env (ברירות מחדל בסיסיות, מתקבל ב-repo אם אין סודות) .env.local (דריסות מקומיות, לעולם לא מתקבל) .env.development (רק במצב פיתוח) .env.development.local (דריסות פיתוח מקומיות) .env.production (רק ב-builds של ייצור) .env.production.local (דריסות ייצור מקומיות) קבצי .local תמיד דורסים קבצים לא-מקומיים. קבצי סביבה ספציפית דורסים את ה-.env הבסיסי. זה מאפשר לך לקבל ברירות מחדל בטוחות ב-.env תוך שמירת סודות ב-.env.local. תבנית נפוצה: .env מכיל NEXT_PUBLIC_SITE_URL=https://yoursite.com כברירת מחדל לייצור. .env.local דורס אותו ל-http://localhost:3000 לפיתוח מקומי. לא צריך שינויי קוד כדי לעבור בין סביבות.

PRO TIP

טעות 1: לשכוח להוסיף .env ל-.gitignore לפני ה-commit הראשון. ברגע שקובץ נעקב על ידי Git, הוספה שלו ל-.gitignore מאוחר יותר לא מסירה אותו מההיסטוריה. צריך git rm --cached .env כדי להפסיק לעקוב, ואז force push. אם כבר דחפת ל-repo ציבורי, החלף כל מפתח בקובץ הזה מיד. המפתחות הישנים בהיסטוריית Git לנצח. טעות 2: שימוש בקידומת NEXT_PUBLIC_ על מפתחות סודיים. NEXT_PUBLIC_STRIPE_SECRET_KEY גלוי ב-bundle של הדפדפן. כל אחד יכול לבדוק אותו. השתמש בקידומת הציבורית רק עבור ערכים שבטוח לחשוף, כמו כתובת URL של האתר או מפתח API ציבורי. טעות 3: שיתוף קבצי .env דרך Slack או אימייל. השתמש במנהל סיסמאות, כספת סודות, או כלי שיתוף מאובטח. קבצי .env בהיסטוריית צ'אט מאונדקסים, נשמרים במטמון, ומגובים במקומות שאתה לא יכול לשלוט בהם. טעות 4: לא ליצור קובץ .env.example. זו תבנית שמראה אילו משתנים האפליקציה מצפה להם, בלי הערכים האמיתיים. קבל את זה ב-repo כדי שמפתחים חדשים ידעו מה למלא. API_KEY= DATABASE_URL= NEXT_PUBLIC_SITE_URL=http://localhost:3000 טעות 5: לוגג משתני סביבה במהלך דיבוג ולשכוח להסיר את הודעות הלוג. console.log(process.env) משפריץ כל סוד לכל שירות לוגים שאתה משתמש בו.

PATTERN

בייצור, לא משתמשים בקבצי .env. מגדירים משתני סביבה ישירות בפלטפורמת האירוח. Vercel: Settings > Environment Variables. הוסף כל זוג מפתח-ערך. בחר לאילו סביבות זה חל (Production, Preview, Development). Railway: לשונית Variables בהגדרות השירות. AWS: Parameter Store או Secrets Manager. העיקרון זהה בכל מקום. סודות חיים בפלטפורמה, לא בקבצים. הקוד שלך קורא מ-process.env ללא קשר למקור הערכים. מקומית הם באים מ-.env. בייצור הם באים מהפלטפורמה. הקוד שלך לא צריך לדעת את ההבדל.