Dokumentacja interfejsu wiersza poleceń Firebase

Wiersz poleceń Firebase (GitHub) udostępnia różne narzędzia do zarządzania, wyświetlania i wdrażania projektów Firebase.

Zanim użyjesz wiersza poleceń Firebase, skonfiguruj projekt Firebase.

Konfigurowanie lub aktualizowanie interfejsu wiersza poleceń

Instalowanie interfejsu wiersza poleceń Firebase

Interfejs wiersza poleceń Firebase możesz zainstalować za pomocą metody dopasowanej do systemu operacyjnego, poziomu doświadczenia lub przypadku użycia. Niezależnie od tego, jak zainstalujesz interfejs wiersza poleceń, masz dostęp do tych samych funkcji i polecenia firebase.

Windows macOS Linux

Windows

Interfejs wiersza poleceń Firebase dla systemu Windows można zainstalować, korzystając z jednego z tych sposobów:

macOS lub Linux

Aby zainstalować interfejs wiersza poleceń Firebase na komputerze z systemem macOS lub Linux, możesz użyć jednej z tych opcji:

Logowanie się i testowanie interfejsu wiersza poleceń Firebase

Po zainstalowaniu interfejsu wiersza poleceń musisz się uwierzytelnić. Następnie możesz potwierdzić uwierzytelnianie, podając listę projektów Firebase.

1. Zaloguj się w Firebase za pomocą konta Google, wykonując to polecenie:

   firebase login

   To polecenie łączy Twój komputer lokalny z Firebase i daje Ci dostęp do projektów Firebase.

2. Sprawdź, czy wiersz poleceń jest prawidłowo zainstalowany i czy ma dostęp do Twojego konta, wyświetlając listę projektów Firebase. Uruchom to polecenie:

   firebase projects:list

   Wyświetlana lista powinna być taka sama jak projekty Firebase wymienione w konsoli Firebase.

Aktualizowanie do najnowszej wersji interfejsu wiersza poleceń

Zazwyczaj warto korzystać z najnowszej wersji interfejsu wiersza poleceń Firebase.

Sposób aktualizacji wersji interfejsu wiersza poleceń zależy od systemu operacyjnego i sposobu zainstalowania interfejsu wiersza poleceń.

Korzystanie z interfejsu wiersza poleceń w systemach CI

Narzędzie wiersza poleceń Firebase wymaga przeglądarki do uwierzytelnienia, ale jest w pełni zgodne z CI i innymi środowiskami bez głowy.

1. Na komputerze z przeglądarką zainstaluj interfejs wiersza poleceń Firebase.

2. Rozpocznij proces logowania, uruchamiając to polecenie:

   firebase login:ci

3. Otwórz podany adres URL i zaloguj się na konto Google.

4. Wydrukuj nowy token odświeżania. Obecna sesja CLI nie zostanie przerwana.

5. Przechowuj token wyjściowy w bezpiecznym, ale łatwo dostępnym miejscu w systemie CI.

6. Użyj tego tokena podczas uruchamiania poleceń firebase. Możesz użyć jednej z tych opcji:

   • Opcja 1: zapisz token jako zmienną środowiskową FIREBASE_TOKEN. Twój system będzie automatycznie używać tokena.

   • Opcja 2: uruchom wszystkie polecenia firebase z flagą --token TOKEN w systemie CI.
     W następującej kolejności: flaga, zmienna środowiskowa, wybrany projekt Firebase.

Inicjowanie projektu Firebase

Wiele typowych zadań wykonywanych za pomocą wiersza poleceń, takich jak wdrażanie w projekcie Firebase, wymaga katalogu projektu. Utwórz katalog projektu za pomocą polecenia firebase init. Katalog projektu jest zwykle tym samym katalogiem co katalog główny kontroli źródła, a po uruchomieniu firebase init zawiera plik konfiguracji firebase.json.

Aby zainicjować nowy projekt Firebase, uruchom to polecenie w katalogu aplikacji:

firebase init

Polecenie firebase init poprowadzi Cię przez konfigurowanie katalogu projektu i niektórych usług Firebase. Podczas inicjowania projektu interfejs wiersza poleceń Firebase prosi o wykonanie tych czynności:

• Wybierz usługi Firebase, które chcesz skonfigurować w projekcie Firebase.

  Na tym etapie możesz skonfigurować konkretne pliki w przypadku wybranych produktów. Więcej informacji o tych konfiguracjach znajdziesz w dokumentacji konkretnego produktu (np. Hosting). Pamiętaj, że zawsze możesz uruchomić polecenie firebase init, aby skonfigurować więcej usług Firebase.

• Wybierz domyślny projekt Firebase.

  Ten krok powoduje powiązanie bieżącego katalogu projektu z projektem Firebase, aby polecenia dotyczące konkretnego projektu (np. firebase deploy) były wykonywane w odpowiednim projekcie Firebase.

  Możesz też powiązać wiele projektów Firebase (np. projekt testowy i produkcyjny) z tym samym katalogiem projektu.

Pod koniec inicjalizacji Firebase automatycznie tworzy w katalogu głównym lokalnej aplikacji te 2 pliki:

• Plik konfiguracji firebase.json, który zawiera konfigurację projektu.

• Plik .firebaserc, w którym są przechowywane aliasy projektu.

plik firebase.json;

Polecenie firebase init tworzy plik konfiguracji firebase.json w katalogu głównym katalogu projektu.

Plik firebase.json jest wymagany do wdrażania zasobów za pomocą interfejsu wiersza poleceń Firebase, ponieważ określa, które pliki i ustawienia z katalogu projektu są wdrażane do projektu Firebase. Ponieważ niektóre ustawienia mogą być zdefiniowane w katalogu projektu lub na konsoli Firebase, upewnij się, że rozwiązujesz wszelkie potencjalne konflikty wdrożenia.

Większość opcji Firebase Hosting możesz skonfigurować bezpośrednio w pliku firebase.json. W przypadku innych usług Firebase, które można wdrożyć za pomocą interfejsu wiersza poleceń Firebase, polecenie firebase init tworzy określone pliki, w których możesz zdefiniować ustawienia tych usług, np. plik index.js dla usługi Cloud Functions. W pliku firebase.json możesz też skonfigurować haczyki przed wdrożeniem lub po wdrożeniu.

Poniżej znajduje się przykładowy plik firebase.json z ustawieniami domyślnymi, jeśli podczas inicjalizacji wybierzesz Firebase Hosting, Cloud Firestore i Cloud Functions for Firebase (z wybranymi opcjami źródła i linta TypeScript).

{
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ]
  },
  "firestore": {
      "rules": "firestore.rules",
      "indexes": "firestore.indexes.json"
  },
  "functions": {
    "predeploy": [
      "npm --prefix \"$RESOURCE_DIR\" run lint",
      "npm --prefix \"$RESOURCE_DIR\" run build"
    ]
  }
}

Domyślnie używany jest plik firebase.json, ale możesz podać flagę --config PATH, aby podać inny plik konfiguracji.

Konfiguracja wielu baz danych Cloud Firestore

Gdy uruchomisz firebase init, plik firebase.json będzie zawierać jeden klucz firestore odpowiadający domyślnej bazie danych projektu, jak pokazano powyżej.

Jeśli Twój projekt zawiera wiele baz danych Cloud Firestore, zmodyfikuj plik firebase.json, aby powiązać z każdą z nich różne pliki źródłowe indeksu Cloud Firestore Security Rules i bazy danych. Zmodyfikuj plik za pomocą tablicy JSON z pojedynczym wpisem dla każdej bazy danych.

      "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 plików, które mają być ignorowane podczas wdrażania

Podczas wdrażania funkcji interfejs wiersza poleceń automatycznie określa listę plików w katalogu functions, które należy zignorować. Zapobiega to wdrażaniu na zapleczu niepotrzebnych plików, które mogłyby zwiększyć rozmiar wdrożenia.

Lista plików ignorowanych domyślnie, wyświetlana w formacie JSON:

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

Jeśli dodasz własne wartości niestandardowe dla atrybutu ignore w elementach firebase.json, pamiętaj, aby zachować (lub dodać, jeśli brakuje) listę plików pokazaną powyżej.

Zarządzanie aliasami projektu

Z jedną katalogiem projektu możesz powiązać wiele projektów Firebase. Możesz na przykład używać jednego projektu Firebase na potrzeby testów, a drugiego na potrzeby produkcji. Korzystając z różnych środowisk projektów, możesz weryfikować zmiany przed wdrożeniem ich w produkcji. Polecenie firebase use umożliwia przełączanie się między aliasami oraz tworzenie nowych aliasów.

Dodawanie aliasu projektu

Gdy wybierzesz projekt Firebase podczas inicjalizacji projektu, zostanie mu automatycznie przypisany alias default. Aby jednak zezwalać na uruchamianie poleceń dotyczących konkretnego projektu w ramach innego projektu Firebase, ale nadal używać tego samego katalogu projektu, uruchom to polecenie w katalogu projektu:

firebase use --add

To polecenie spowoduje wyświetlenie prompta z prośbą o wybranie innego projektu Firebase i przypisanie mu aliasu. Przypisania aliasów są zapisywane w pliku .firebaserc w katalogu projektu.

Używanie aliasów projektów

Aby używać przypisanych aliasów projektów Firebase, uruchom dowolne z tych poleceń w katalogu projektu.

Możesz zmienić projekt używany jako aktywny, podając flagę --project w dowolnym poleceniu wiersza poleceń. Na przykład: możesz skonfigurować interfejs wiersza poleceń tak, aby działał w projektie Firebase, do którego przypisałeś alias staging. Jeśli chcesz wykonać pojedyncze polecenie w projekcie Firebase, do którego przypisałeś alias prod, możesz użyć np. polecenia firebase deploy --project=prod.

Kontrola wersji i aliasy projektów

Ogólnie rzecz biorąc, aby umożliwić zespołowi udostępnianie aliasów projektów, musisz dodać plik .firebaserc do kontroli wersji. Jednak w przypadku projektów open source lub szablonów startowych nie należy zazwyczaj sprawdzać pliku .firebaserc.

Jeśli masz projekt deweloperski, którego używasz tylko Ty, możesz użyć parametru --project z każdym poleceniem lub uruchomić firebase use PROJECT_ID bez przypisywania aliasu do projektu Firebase.

Serwowanie i testowanie projektu Firebase lokalnie

Przed wdrożeniem projektu Firebase w wersji produkcyjnej możesz wyświetlić i przetestować go w adresach URL hostowanych lokalnie. Jeśli chcesz przetestować tylko wybrane funkcje, możesz użyć listy oddzielonych przecinkami w flagach w komendzie firebase serve.

Jeśli chcesz wykonać jedną z tych czynności, uruchom to polecenie w głównym katalogu projektu lokalnego:

• Wyświetlanie treści statycznych aplikacji hostowanej w Firebase.
• Używasz Cloud Functions do generowania dynamicznych treści dla Firebase Hosting i chcesz użyć funkcji HTTP w wersji produkcyjnej (wdrożonej), aby emulować Hosting w lokalnym adresie URL.

firebase serve --only hosting

Emulowanie projektu za pomocą lokalnych funkcji HTTP

Uruchom dowolne z tych poleceń w katalogu projektu, aby emulować projekt za pomocą lokalnych funkcji HTTP.

• Aby emulować funkcje HTTP i hosting na potrzeby testowania adresów URL lokalnych, użyj jednego z tych poleceń:

  firebase serve

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

• Aby emulować tylko funkcje HTTP, użyj tego polecenia:

  firebase serve --only functions

Testowanie na innych urządzeniach lokalnych

Domyślnie usługa firebase serve odpowiada tylko na żądania wysyłane przez usługę localhost. Oznacza to, że będziesz mieć dostęp do hostowanych treści z poziomu przeglądarki na komputerze, ale nie z innych urządzeń w sieci. Jeśli chcesz przetestować inne urządzenia lokalne, użyj flagi --host, np.:

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

Wdrażanie w projekcie Firebase

Interfejs wiersza poleceń Firebase zarządza wdrażaniem kodu i komponentów do projektu Firebase, w tym:

• Nowe wersje witryn Firebase Hosting
• Nowe, zaktualizowane lub istniejące Cloud Functions for Firebase
• Nowe lub zaktualizowane schematy i oprogramowanie sprzęgające na potrzeby Firebase Data Connect
• Reguły dotyczące Firebase Realtime Database
• Reguły dotyczące Cloud Storage for Firebase
• Reguły dotyczące Cloud Firestore
• Indeksy dla zadania Cloud Firestore

Aby wdrożyć projekt w Firebase, uruchom to polecenie w katalogu projektu:

firebase deploy

Opcjonalnie możesz dodać komentarz do każdego wdrożenia. Ten komentarz będzie wyświetlany wraz z innymi informacjami o wdrożeniu na Firebase Hostingstronie projektu. Przykład:

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

Gdy używasz polecenia firebase deploy, pamiętaj o tych kwestiach:

• Aby wdrożyć zasoby z katalogu projektu, katalog projektu musi zawierać plik firebase.json. Ten plik jest tworzony automatycznie przez polecenie firebase init.

• Domyślnie firebase deploy tworzy wersję wszystkich zasobów do wdrożenia w katalogu projektu. Aby wdrożyć określone usługi lub funkcje Firebase, użyj częściowego wdrożenia.

Konflikty wdrożenia reguł zabezpieczeń

W przypadku usług Firebase Realtime Database, Cloud Storage for Firebase i Cloud Firestore reguły zabezpieczeń możesz zdefiniować w lokalnym katalogu projektu lub w konsoli Firebase.

Inną opcją, która pozwala uniknąć konfliktów podczas wdrażania, jest częściowe wdrażanie i definiowanie reguł tylko w konsoli Firebase.

Limity wdrożeń

Możliwe (choć mało prawdopodobne), że przekroczysz limit, który ogranicza szybkość lub liczbę operacji wdrażania Firebase. Na przykład podczas wdrażania bardzo dużej liczby funkcji możesz otrzymać komunikat o błędzie HTTP 429 Quota. Aby rozwiązać takie problemy, spróbuj wykorzystać częściowe wdrożenie.

Cofanie wdrożenia

Możesz cofnąć wdrożenie Firebase Hosting na stronie Firebase Hosting projektu, wybierając działanie Cofnij dla wybranej wersji.

Obecnie nie można cofnąć wersji reguł zabezpieczeń w przypadku Firebase Realtime Database, Cloud Storage for Firebase lub Cloud Firestore.

Wdrażanie konkretnych usług Firebase

Jeśli chcesz wdrożyć tylko określone usługi lub funkcje Firebase, możesz użyć w flagach polecenia firebase deploy listy oddzielonych przecinkami. Na przykład polecenie poniżej wdraża reguły bezpieczeństwa Firebase Hosting dotyczące treści i Cloud Storage.

firebase deploy --only hosting,storage

W tabeli poniżej znajdziesz listę usług i funkcji dostępnych w przypadku częściowego wdrożenia. Nazwy w flagach odpowiadają kluczom w pliku konfiguracji firebase.json.

Wdrażanie określonych funkcji

Podczas wdrażania funkcji możesz kierować je na konkretne funkcje. Przykład:

firebase deploy --only functions:function1

firebase deploy --only functions:function1,functions:function2

Inną opcją jest grupowanie funkcji w plikach eksportu /functions/index.js. Funkcja grupowania umożliwia wdrażanie wielu funkcji za pomocą jednego polecenia.

Aby zdefiniować groupA i groupB, możesz na przykład użyć tych funkcji:

var functions = require('firebase-functions/v1');

exports.groupA = {
  function1: functions.https.onRequest(...),
  function2: functions.database.ref('\path').onWrite(...)
}
exports.groupB = require('./groupB');

W tym przykładzie oddzielny plik functions/groupB.js zawiera dodatkowe funkcje, które definiują funkcje w pliku groupB. Przykład:

var functions = require('firebase-functions/v1');

exports.function3 = functions.storage.object().onChange(...);
exports.function4 = functions.analytics.event('in_app_purchase').onLog(...);

W tym przykładzie możesz wdrożyć wszystkie funkcje groupA, uruchamiając to polecenie w katalogu projektu:

firebase deploy --only functions:groupA

Możesz też ukierunkować funkcję na określony element w grupie, uruchamiając to polecenie:

firebase deploy --only functions:groupA.function1,groupB.function4

Usuwanie funkcji

Wiersz poleceń Firebase obsługuje te polecenia i opcje umożliwiające usuwanie wcześniej wdrożonych funkcji:

• Usuwa wszystkie funkcje pasujące do określonej nazwy we wszystkich regionach:

  firebase functions:delete FUNCTION-1_NAME

• Usuwa określoną funkcję uruchomioną w regionie innym niż domyślny:

  firebase functions:delete FUNCTION-1_NAME --region REGION_NAME

• Usuwa więcej niż 1 funkcję:

  firebase functions:delete FUNCTION-1_NAME FUNCTION-2_NAME

• Usuwa określoną grupę funkcji:

  firebase functions:delete GROUP_NAME

• Ominięcie prośby o potwierdzenie:

  firebase functions:delete FUNCTION-1_NAME --force

Konfigurowanie skryptowanych zadań przed wdrożeniem i po wdrożeniu

Aby wykonać zadania wstępnej lub końcowej implementacji, możesz połączyć skrypty powłoki z poleceniem firebase deploy. Na przykład skrypt przed wdrożeniem może przetłumaczyć kod TypeScript na JavaScript, a element wywoływania po wdrożeniu może powiadomić administratorów o nowym wdrożeniu treści witryny do Firebase Hosting.

Aby skonfigurować uchwyty przed wdrożeniem lub po wdrożeniu, dodaj skrypty bash do pliku konfiguracyjnego firebase.json. Scenariusze krótkich tekstów możesz zdefiniować bezpośrednio w pliku firebase.json lub odwoływać się do innych plików w katalogu projektu.

Na przykład poniższy skrypt to wyrażenie firebase.json dla zadania po wdrożeniu, które wysyła wiadomość do Slacka po pomyślnym wdrożeniu do Firebase Hosting.

"hosting": {
  // ...

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

Plik skryptu messageSlack.sh znajduje się w katalogu projektu i wygląda tak:

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

Możesz skonfigurować predeploy i postdeploy dla dowolnych zasobów, które możesz wdrożyć. Pamiętaj, że uruchomienie polecenia firebase deploy uruchamia wszystkie zadania przed wdrożeniem i po jego zakończeniu zdefiniowane w pliku firebase.json. Aby uruchomić tylko zadania powiązane z konkretną usługą Firebase, użyj poleceń częściowego wdrożenia.

Zarówno predeploy, jak i postdeploy wyświetlają w terminalu standardowe dane wyjściowe i strumień błędów skryptów. W przypadku niepowodzenia:

• Jeśli nie uda się uruchomić przedwdrożeniowego haka zgodnie z oczekiwaniami, wdrożenie zostanie anulowane.
• Jeśli wdrożenie nie powiedzie się z jakiegokolwiek powodu, nie zostaną uruchomione żadne haka po wdrożeniu.

Zmienne środowiskowe

W skryptach uruchamianych w punktach zaczepienia przed wdrożeniem i po wdrożeniu dostępne są te zmienne środowiskowe:

• $GCLOUD_PROJECT: identyfikator aktywnego projektu
• $PROJECT_DIR: katalog główny zawierający plik firebase.json
• $RESOURCE_DIR: (dotyczy tylko skryptów hosting i functions) lokalizacja katalogu zawierającego zasoby Hosting lub Cloud Functions do wdrożenia

Zarządzanie wieloma instancjami Realtime Database

Projekt Firebase może mieć wiele instancji Firebase Realtime Database. Domyślnie polecenia wiersza poleceń działają z domyślną instancją bazy danych.

Możesz jednak wchodzić w interakcje z niedomyślnym wystąpieniem bazy danych, używając flagi --instance DATABASE_NAME. Flaga --instance jest obsługiwana przez te polecenia:

• firebase database:get
• firebase database:profile
• firebase database:push
• firebase database:remove
• firebase database:set
• firebase database:update

Informacje o poleceniach

Polecenia administracyjne w interfejsie wiersza poleceń

Polecenia zarządzania projektem

Wdrażanie i rozwijanie lokalnie

Te polecenia umożliwiają wdrażanie witryny Firebase Hosting i wchodzenie z nią w interakcje.

App Distribution poleceń

App Hosting poleceń

Authentication (polecenia dotyczące zarządzania użytkownikami)

Cloud Firestore poleceń

Cloud Functions for Firebase poleceń

Więcej informacji znajdziesz w dokumentacji konfiguracji środowiska.

Crashlytics poleceń

Data Connect poleceń

Te polecenia i ich przypadki użycia są opisane bardziej szczegółowo w Data Connectprzewodniku po interfejsie wiersza poleceń.

Extensions poleceń

Extensions polecenia wydawcy

Hosting poleceń

Realtime Database poleceń

Pamiętaj, że możesz utworzyć początkową, domyślną instancję Realtime Database w konsoli Firebase lub za pomocą ogólnego firebase initprzepływu pracy lub konkretnego firebase init databaseprzepływu.

Po utworzeniu instancji możesz nimi zarządzać zgodnie z informacjami podanymi w artykule Zarządzanie wieloma instancjami Realtime Database.

Remote Config poleceń