מסמך עזר של Firebase CLI

‫Firebase CLI‏ (GitHub) מספק מגוון כלים לניהול, לצפייה ולפריסה בפרויקטים של Firebase.

לפני שמשתמשים ב-CLI של Firebase, צריך להגדיר פרויקט Firebase.

הגדרה או עדכון של ה-CLI

התקנת Firebase CLI

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

‫Windows ‫macOS ‫Linux

‫Windows

אפשר להתקין את Firebase CLI ל-Windows באחת מהדרכים הבאות:

‫macOS או Linux

אפשר להתקין את Firebase CLI ב-macOS או ב-Linux באמצעות אחת מהאפשרויות הבאות:

התחברות ובדיקה של ה-CLI של Firebase

אחרי שמתקינים את ה-CLI, צריך לבצע אימות. אחרי זה תוכלו לאמת את האימות על ידי הצגת רשימה של הפרויקטים ב-Firebase.

1. מתחברים ל-Firebase באמצעות חשבון Google על ידי הפעלת הפקודה הבאה:

   firebase login

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

2. כדי לבדוק שה-CLI מותקן בצורה תקינה ושיש לו גישה לחשבון, מריצים את הפקודה הבאה כדי להציג את הפרויקטים ב-Firebase. מריצים את הפקודה הבאה:

   firebase projects:list

   הרשימה שמוצגת צריכה להיות זהה לרשימת הפרויקטים ב-Firebase שמופיעה במסוף Firebase.

עדכון לגרסה האחרונה של CLI

בדרך כלל, מומלץ להשתמש בגרסה הכי עדכנית של Firebase CLI.

הדרך לעדכן את גרסת ה-CLI תלויה במערכת ההפעלה ובאופן ההתקנה של ה-CLI.

הסרת Firebase CLI

הדרך להסרת ה-CLI תלויה במערכת ההפעלה ובאופן ההתקנה של ה-CLI.

שימוש ב-CLI עם מערכות CI

מומלץ לבצע אימות באמצעות Application Default Credentials כשמשתמשים ב-CLI עם מערכות CI.

(מומלץ) שימוש ב-Application Default Credentials

‫Firebase CLI יזהה וישתמש בפרטי הכניסה ב-Application Default Credentials אם הם מוגדרים. הדרך הכי פשוטה לאמת את ה-CLI ב-CI ובסביבות אחרות ללא ממשק משתמש היא להגדיר את פרטי הכניסה ב-Application Default Credentials.

‫(Legacy) שימוש ב-FIREBASE_TOKEN

לחלופין, אפשר לבצע אימות באמצעות FIREBASE_TOKEN. השיטה הזו פחות מאובטחת מ-Application Default Credentials, וכבר לא מומלצת.

1. במכונה עם דפדפן, מתקינים את Firebase CLI.

2. כדי להתחיל את תהליך הכניסה, מריצים את הפקודה הבאה:

   firebase login:ci

3. נכנסים לכתובת ה-URL שסופקה, ואז מתחברים באמצעות חשבון Google.

4. הדפסה של טוקן רענון חדש. הסשן הנוכחי של ה-CLI לא יושפע.

5. מאחסנים את אסימון הפלט בצורה מאובטחת אבל נגישה במערכת ה-CI.

6. משתמשים באסימון הזה כשמריצים פקודות firebase. אפשר להשתמש באחת משתי האפשרויות הבאות:

   • אפשרות 1: אחסון הטוקן כמשתנה הסביבה FIREBASE_TOKEN. המערכת תשתמש בטוקן באופן אוטומטי.

   • אפשרות 2: מריצים את כל הפקודות של firebase עם הדגל --token TOKEN במערכת ה-CI.
     זהו סדר העדיפות לטעינת טוקנים: דגל, משתנה סביבתי, פרויקט Firebase רצוי.

הפעלת פרויקט Firebase

הרבה משימות נפוצות שמבצעים באמצעות ה-CLI, כמו פריסה לפרויקט Firebase, דורשות ספריית פרויקט. יוצרים ספריית פרויקט באמצעות הפקודה firebase init. תיקיית הפרויקט היא בדרך כלל אותה תיקייה כמו השורש של בקרת המקור, ואחרי שמריצים את firebase init, התיקייה מכילה קובץ הגדרות של firebase.json.

כדי לאתחל פרויקט חדש ב-Firebase, מריצים את הפקודה הבאה מתוך ספריית האפליקציה:

firebase init

הפקודה firebase init מנחה אתכם בהגדרת ספריית הפרויקט וכמה מוצרים של Firebase. במהלך אתחול הפרויקט, ממשק Firebase CLI מבקש מכם לבצע את המשימות הבאות:

• בוחרים פרויקט ברירת מחדל ב-Firebase.

  בשלב הזה משייכים את ספריית הפרויקט הנוכחית לפרויקט Firebase, כדי שפקודות ספציפיות לפרויקט (כמו firebase deploy) יפעלו מול פרויקט Firebase המתאים.

  אפשר גם לשייך כמה פרויקטים ב-Firebase (למשל פרויקט Staging ופרויקט Production) לאותה תיקיית פרויקט.

• בוחרים את מוצרי Firebase שרוצים להגדיר בפרויקט Firebase.

  בשלב הזה תתבקשו להגדיר קבצים ספציפיים למוצרים או לתכונות שבחרתם. פרטים נוספים על ההגדרות האלה מופיעים במסמכי העזרה של המוצר הספציפי (לדוגמה, Hosting או Authentication). שימו לב שתמיד אפשר להריץ את הפקודה firebase init מאוחר יותר כדי להגדיר מוצרים נוספים של Firebase.

בסיום האתחול, Firebase יוצר באופן אוטומטי את שני הקבצים הבאים בתיקיית השורש של האפליקציה המקומית:

• קובץ הגדרות firebase.json שבו מפורטות ההגדרות של הפרויקט.

• קובץ .firebaserc שבו מאוחסנים כינויים של הפרויקט.

הקובץ firebase.json

הפקודה firebase init יוצרת קובץ הגדרות firebase.json בספריית השורש של הפרויקט.

קובץ firebase.json נדרש כדי לפרוס נכסים באמצעות Firebase CLI, כי הוא מציין אילו קבצים והגדרות מספריית הפרויקט ייפרסו בפרויקט Firebase (כמו הגדרות Hosting, הגדרות ספק Authentication, כללי אבטחה והגדרות Cloud Functions). חלק מההגדרות יכולות להיות מוגדרות בספריית הפרויקט או במסוף Firebase, לכן חשוב לפתור בעיות פוטנציאליות של פריסה.

אפשר להגדיר את רוב האפשרויות של Firebase Hosting ישירות בקובץ firebase.json. עם זאת, עבור שירותי Firebase אחרים שאפשר לפרוס באמצעות ה-CLI של Firebase, הפקודה firebase init יוצרת קבצים ספציפיים שבהם אפשר להגדיר את ההגדרות של השירותים האלה, כמו קובץ index.js עבור Cloud Functions. אפשר גם להגדיר predeploy או postdeploy hooks בקובץ firebase.json.

קובץ firebase.json הבא הוא דוגמה מקיפה שמציגה אפשרויות הגדרה לשירותים רבים של Firebase. הוא גם מדגים תכונות כמו Cloud Functions עם כמה בסיסי קוד, הגדרה של Local Emulator Suite ותבנית Remote Config. שימו לב שקובץ firebase.json של פרויקט מסוים יכיל רק הגדרות של שירותי Firebase שהוגדרו עבור הפרויקט הספציפי הזה (לדוגמה, רק Firebase Hosting ו-Cloud Functions). הוספת המפתח $schema מאפשרת אימות והשלמה אוטומטית בהרבה עורכי קוד.

    {
      "$schema": "https://raw.githubusercontent.com/firebase/firebase-tools/master/schema/firebase-config.json",
      "hosting": {
        "public": "public",
        "ignore": [
          "firebase.json",
          "**/.*",
          "**/node_modules/**"
        ],
        "cleanUrls": true,
        "trailingSlash": false
      },
      "apphosting": {
        "backendId": "my-app",
        "rootDir": "backend",
        "ignore": [
          "firebase.json",
          "**/.*",
          "**/node_modules/**"
        ]
      },
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json"
      },
      "storage": {
        "rules": "storage.rules"
      },
      "database": {
        "rules": "database.rules.json"
      },
      "dataconnect": {
        "source": "dataconnect",
        "location": "us-central1"
      },
      "functions": [
        {
          "source": "functions",
          "codebase": "default",
          "ignore": [
            "**/.*",
            "**/node_modules/**"
          ],
          "predeploy": [
            "npm --prefix \"$RESOURCE_DIR\" run lint",
            "npm --prefix \"$RESOURCE_DIR\" run build"
          ]
        }
      ],
      "emulators": {
        "auth": {
          "port": 9099
        },
        "functions": {
          "port": 5001
        },
        "firestore": {
          "port": 8080
        },
        "hosting": {
          "port": 5000
        },
        "storage": {
          "port": 9199
        },
        "ui": {
          "enabled": true,
          "port": 4000
        },
        "singleProjectMode": true
      },
      "extensions": {
        "my-storage-resizer": "firebase/storage-resize-images@^0.1.0"
      },
      "auth": {
        "providers": {
          "anonymous": true,
          "emailPassword": true,
          "googleSignIn": {
            "oAuthBrandDisplayName": "My App",
            "supportEmail": "support@myapp.com"
          }
        }
      },
      "remoteconfig": {
        "template": "remoteconfig.template.json"
      }
    }

אמנם נעשה שימוש ב-firebase.json כברירת מחדל, אבל אפשר להעביר את הדגל --config PATH כדי לציין קובץ הגדרות חלופי.

הגדרה של כמה מסדי נתונים של Cloud Firestore

כשמריצים את הפקודה firebase init, קובץ firebase.json מכיל מפתח firestore יחיד שמתאים למסד הנתונים שמוגדר כברירת מחדל בפרויקט, כמו שמוצג בדוגמה הקודמת.

אם הפרויקט מכיל כמה מסדי נתונים של Cloud Firestore, צריך לערוך את הקובץ firebase.json כדי לשייך קובצי מקור שונים של אינדקסים של Cloud Firestore Security Rules ומסדי נתונים לכל מסד נתונים. משנים את הקובץ באמצעות מערך JSON, עם רשומה אחת לכל מסד נתונים.

      "firestore": [
        {
          "database": "(default)",
          "rules": "firestore.default.rules",
          "indexes": "firestore.default.indexes.json"
        },
        {
          "database": "ecommerce",
          "rules": "firestore.ecommerce.rules",
          "indexes": "firestore.ecommerce.indexes.json"
        }
      ],

Cloud Functions קבצים להתעלמות במהלך הפריסה

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

רשימת הקבצים שמתעלמים מהם כברירת מחדל, שמוצגת בפורמט JSON:

"ignore": [
  ".git",
  ".runtimeconfig.json",
  "firebase-debug.log",
  "firebase-debug.*.log",
  "node_modules"
]

אם מוסיפים ערכים מותאמים אישית ל-ignore ב-firebase.json, צריך לוודא ששומרים (או מוסיפים, אם הם חסרים) את רשימת הקבצים שמוצגת ברשימה הקודמת.

ניהול כינויים של פרויקטים

אפשר לשייך כמה פרויקטים של Firebase לאותה תיקיית פרויקט. לדוגמה, יכול להיות שתרצו להשתמש בפרויקט אחד ב-Firebase ל-Staging ובפרויקט אחר לייצור. שימוש בסביבות פרויקט שונות מאפשר לכם לאמת שינויים לפני הפריסה לייצור. הפקודה firebase use מאפשרת לעבור בין כינויים וגם ליצור כינויים חדשים.

הוספת כינוי לפרויקט

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

firebase use --add

הפקודה הזו תבקש מכם לבחור פרויקט אחר ב-Firebase ולהקצות את הפרויקט ככינוי. הקצאות של כינויים נכתבות לקובץ .firebaserc בתוך ספריית הפרויקט.

שימוש בכינויים לפרויקטים

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

כדי לשנות את הפרויקט הפעיל, אפשר להעביר את הדגל --project עם כל פקודה ב-CLI. לדוגמה: אפשר להגדיר את ה-CLI כך שיפעל מול פרויקט Firebase שהקציתם לו את הכינוי staging. אם רוצים להריץ פקודה אחת על פרויקט Firebase שהוקצה לו הכינוי prod, אפשר להריץ למשל את הפקודה firebase deploy --project=prod.

בקרת מקורות וכינויי פרויקטים

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

אם יש לכם פרויקט פיתוח לשימושכם בלבד, אתם יכולים להעביר את הדגל --project עם כל פקודה או להריץ את הפקודה firebase use PROJECT_ID בלי להקצות כינוי לפרויקט Firebase.

הצגה ובדיקה של פרויקט Firebase באופן מקומי

אתם יכולים לראות ולבדוק את פרויקט Firebase בכתובות URL שמתארחות באופן מקומי לפני הפריסה בסביבת הייצור. אם רוצים לבדוק רק תכונות נבחרות, אפשר להשתמש ברשימה מופרדת בפסיקים בדגל בפקודה firebase serve.

מריצים את הפקודה הבאה מהספרייה הראשית של פרויקט מקומי אם רוצים לבצע אחת מהמשימות הבאות:

• צפייה בתוכן הסטטי של האפליקציה שמתארחת ב-Firebase.
• אתם משתמשים ב-Cloud Functions כדי ליצור תוכן דינמי עבור Firebase Hosting ואתם רוצים להשתמש בפונקציות HTTP בסביבת הייצור (פריסה) כדי לבצע אמולציה של Hosting בכתובת URL מקומית.

firebase serve --only hosting

הדמיה של הפרויקט באמצעות פונקציות HTTP מקומיות

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

• כדי לבצע אמולציה של פונקציות HTTP ואירוח לצורך בדיקה של כתובות URL מקומיות, משתמשים באחת מהפקודות הבאות:

  firebase serve

  firebase serve --only functions,hosting // uses a flag

• כדי לבצע אמולציה רק לפונקציות HTTP, משתמשים בפקודה הבאה:

  firebase serve --only functions

בדיקה ממכשירים מקומיים אחרים

כברירת מחדל, firebase serve מגיב רק לבקשות מ-localhost. המשמעות היא שתוכלו לגשת לתוכן המתארח מדפדפן האינטרנט במחשב, אבל לא ממכשירים אחרים ברשת. אם רוצים לבצע בדיקה ממכשירים מקומיים אחרים, משתמשים בדגל --host, כך:

firebase serve --host 0.0.0.0  // accepts requests to any host

פריסה לפרויקט Firebase

‫Firebase CLI מנהל את הפריסה של קוד ונכסים לפרויקט Firebase, כולל:

• פריטים חדשים באתרים שלך Firebase Hosting
• חדש, מעודכן או קיים Cloud Functions for Firebase
• סכימות ורכיבי Connector חדשים או מעודכנים עבור Firebase SQL Connect
• Security Rules של Firebase Realtime Database
• Security Rules של Cloud Storage for Firebase
• Security Rules של Cloud Firestore
• אינדקסים של Cloud Firestore
• הגדרות לאפליקציה Authentication

כדי לפרוס לפרויקט Firebase, מריצים את הפקודה הבאה מספריית הפרויקט:

firebase deploy

אפשר להוסיף הערה לכל פריסה. התגובה הזו תוצג עם פרטי הפריסה האחרים בדף Firebase Hosting של הפרויקט. לדוגמה:

firebase deploy -m "Deploying the best new feature ever."

כשמשתמשים בפקודה firebase deploy, חשוב לשים לב לדברים הבאים:

• כדי לפרוס משאבים מתיקיית פרויקט, חייב להיות בתיקיית הפרויקט קובץ firebase.json. הקובץ הזה נוצר אוטומטית על ידי הפקודה firebase init.

• כברירת מחדל, firebase deploy יוצר גרסת הפצה לכל המשאבים שניתן לפרוס בספריית הפרויקט. כדי לפרוס תכונות או שירותים ספציפיים של Firebase, משתמשים בפריסה חלקית.

פריסת שירותים ספציפיים של Firebase

אם רוצים לפרוס רק תכונות או שירותים ספציפיים של Firebase, אפשר להשתמש ברשימה מופרדת בפסיקים בדגל בפקודה firebase deploy. לדוגמה, הפקודה הבאה פורסת את התוכן Firebase Hosting ואת Cloud Storage Security Rules.

firebase deploy --only hosting,storage

בטבלה הבאה מפורטים השירותים והתכונות שזמינים לפריסה חלקית. השמות בדגלים תואמים למפתחות בקובץ ההגדרות firebase.json.

התנגשויות בהטמעה של Security Rules

במקרה של Firebase Realtime Database,‏ Cloud Storage for Firebase ו-Cloud Firestore, אפשר להגדיר את Security Rules בספריית הפרויקט המקומית או במסוף Firebase.

אפשרות נוספת למניעת התנגשויות בפריסה היא שימוש בפריסה חלקית והגדרה של Security Rules רק במסוף Firebase.

הגדרת משימות מבוססות סקריפט לפני הפריסה ואחרי הפריסה

אפשר לחבר סקריפטים של Shell לפקודה firebase deploy כדי לבצע משימות לפני או אחרי הפריסה. לדוגמה, סקריפט לפני פריסה יכול לבצע המרה של קוד TypeScript לקוד JavaScript, ו-hook אחרי פריסה יכול להודיע לאדמינים על פריסות של תוכן חדש באתר אל Firebase Hosting.

כדי להגדיר פעולות לפני או אחרי פריסה, מוסיפים סקריפטים של Bash לקובץ ההגדרות firebase.json. אפשר להגדיר סקריפטים קצרים ישירות בקובץ firebase.json, או להפנות לקבצים אחרים שנמצאים בספריית הפרויקט.

לדוגמה, הסקריפט הבא הוא הביטוי firebase.json למשימה מסוג postdeploy ששולחת הודעה ב-Slack אחרי פריסה מוצלחת אל Firebase Hosting.

"hosting": {
  // ...

  "postdeploy": "./messageSlack.sh 'Just deployed to Firebase Hosting'",
  "public": "public"
}

קובץ הסקריפט messageSlack.sh נמצא בספריית הפרויקט ונראה כך:

curl -X POST -H 'Content-type: application/json' --data '{"text":"$1"}'
     \https://SLACK_WEBHOOK_URL

אפשר להגדיר ווים (hooks) של predeploy ו-postdeploy לכל אחד מהנכסים שאפשר לפרוס. הערה: הפעלת firebase deploy מפעילה את כל המשימות של לפני הפריסה ואחרי הפריסה שמוגדרות בקובץ firebase.json. כדי להריץ רק את המשימות שמשויכות לשירות ספציפי של Firebase, משתמשים בפקודות פריסה חלקיות.

ה-hooks predeploy ו-postdeploy מדפיסים את הפלט הרגיל ואת זרמי השגיאות של הסקריפטים בטרמינל. במקרים של כשלים, חשוב לשים לב לנקודות הבאות:

• אם פעולת ה-hook לפני הפריסה לא מסתיימת כמצופה, הפריסה מבוטלת.
• אם הפריסה נכשלת מסיבה כלשהי, לא מופעלים ווים של postdeploy.

משתני סביבה

בסקריפטים שפועלים ב-hooks של predeploy ו-postdeploy, משתני הסביבה הבאים זמינים:

• ‫$GCLOUD_PROJECT: מזהה הפרויקט הפעיל
• ‫$PROJECT_DIR: תיקיית השורש שמכילה את הקובץ firebase.json
• ‫$RESOURCE_DIR: (לסקריפטים של hosting ו-functions בלבד) המיקום של הספרייה שמכילה את משאבי Hosting או Cloud Functions שרוצים לפרוס

מכסות פריסה

יכול להיות (אבל זה לא סביר) שתחרגו ממכסה שמגבילה את הקצב או את הנפח של פעולות הפריסה שלכם ב-Firebase. לדוגמה, כשמפעילים מספרים גדולים מאוד של פונקציות, יכול להיות שתופיע הודעת שגיאה HTTP 429 Quota. כדי לפתור בעיות כאלה, אפשר לנסות פריסה חלקית.

החזרה של פריסה

אפשר לבטל פריסה של Firebase Hosting מהפרויקט Firebase Hosting בדף על ידי בחירת הפעולה Rollback (ביטול פריסה) לגרסה הרצויה.

אי אפשר לבטל את העדכונים של Security Rules ב-Firebase Realtime Database,‏ Cloud Storage for Firebase או Cloud Firestore.

הפניות לפקודות

פקודות ניהול ב-CLI

פקודות לניהול פרויקטים

פריסה ופיתוח מקומי

הפקודות האלה מאפשרות לכם לפרוס את האתר Firebase Hosting ולבצע בו פעולות.

פקודות App Distribution

פקודות App Hosting

פקודות Authentication (ניהול משתמשים)

פקודות Cloud Firestore

פקודות Cloud Functions for Firebase

מידע נוסף מופיע במאמרי העזרה בנושא הגדרת הסביבה.

פקודות Crashlytics

פקודות SQL Connect

הפקודות האלה ותרחישי השימוש שלהן מוסברים בפירוט רב יותר במדריך העזר ל-CLI של SQL Connect.

פקודות Extensions

פקודות Extensions לבעלי תוכן דיגיטלי

פקודות Hosting

פקודות Realtime Database

שימו לב שאפשר ליצור את מופע Realtime Database הראשוני שמוגדר כברירת מחדל במסוף Firebase או באמצעות תהליך העבודה הכללי firebase init או התהליך הספציפי firebase init database.

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

פקודות Remote Config