Obsługa błędów Cloud Storage w Flutter

Jeśli masz *.appspot.comdomyślny zasobnik,musisz przejść na abonament Blaze z płatnością według zużycia w projekcie Firebase najpóźniej 2 lutego 2026 r., aby zachować dostęp do domyślnego zasobnika. Więcej informacji

Czasami podczas tworzenia aplikacji coś idzie nie tak i występuje błąd.

W razie wątpliwości przechwyć wyjątek zgłoszony przez funkcję i sprawdź, co mówi komunikat o błędzie.

final storageRef = FirebaseStorage.instance.ref().child("files/uid");
try {
  final listResult = await storageRef.listAll();
} on FirebaseException catch (e) {
  // Caught an exception from Firebase.
  print("Failed with error '${e.code}': ${e.message}");
}

Uwaga: domyślnie zasobnik Cloud Storage for Firebase wymaga Firebase Authentication, aby można było wykonać dowolną czynność na danych lub plikach zasobnika. Możesz zmienić Firebase Security Rules dla Cloud Storage, aby w określonych sytuacjach zezwolić na dostęp bez uwierzytelniania. W większości przypadków stanowczo zalecamy jednak ograniczenie dostępu i skonfigurowanie solidnych reguł bezpieczeństwa (zwłaszcza w przypadku aplikacji produkcyjnych). Pamiętaj, że jeśli używasz Google App Engine i masz domyślny zasobnik Cloud Storage o nazwie w formacie *.appspot.com, musisz wziąć pod uwagę wpływ reguł bezpieczeństwa na dostęp do plików App Engine.

Obsługa komunikatów o błędach

Błędy mogą wystąpić z różnych powodów, np. plik może nie istnieć, użytkownik może nie mieć uprawnień dostępu do wybranego pliku lub może anulować przesyłanie pliku.

Aby prawidłowo zdiagnozować problem i obsłużyć błąd, zapoznaj się z pełną listą wszystkich błędów, które może zgłosić nasz klient, oraz z informacjami o tym, jak one powstają.

Kod	Opis
storage/unknown	Wystąpił nieznany błąd.
storage/object-not-found	W odpowiednim odwołaniu nie ma obiektu.
storage/bucket-not-found	Nie skonfigurowano zasobnika Cloud Storage
storage/project-not-found	Brak projektu skonfigurowanego dla Cloud Storage
storage/quota-exceeded	Limit w przypadku zasobnika Cloud Storage został przekroczony. Jeśli korzystasz z abonamentu Spark, rozważ przejście na abonament Blaze z płatnością za wykorzystanie. Jeśli korzystasz już z abonamentu Blaze, skontaktuj się z zespołem pomocy Firebase. Ważne: od 2 lutego 2026 roku do korzystania z Cloud Storage, nawet z domyślnych zasobników, będzie wymagany abonament Blaze.
storage/unauthenticated	Użytkownik nie jest uwierzytelniony. Uwierzytelnij się i spróbuj ponownie.
storage/unauthorized	Użytkownik nie ma uprawnień do wykonania żądanej czynności. Sprawdź, czy reguły zabezpieczeń są prawidłowe.
storage/retry-limit-exceeded	Przekroczono maksymalny limit czasu operacji (przesyłania, pobierania, usuwania itp.). Spróbuj przesłać go jeszcze raz.
storage/invalid-checksum	Plik na urządzeniu klienta nie jest zgodny z sumą kontrolną pliku otrzymanego przez serwer. Spróbuj przesłać go jeszcze raz.
storage/canceled	Operacja anulowana przez użytkownika.
storage/invalid-event-name	Podano nieprawidłową nazwę zdarzenia. Musi to być jedna z wartości: [running, progress, pause]
storage/invalid-url	Nieprawidłowy adres URL przekazany do refFromURL(). Musi mieć format gs://bucket/object lub https://firebasestorage.googleapis.com/v0/b/bucket/o/object?token=<TOKEN>.
storage/invalid-argument	Argument przekazany do funkcji put() musi być tablicą File, Blob lub UInt8. Argument przekazany do funkcji putString() musi być ciągiem znaków w formacie surowym, Base64 lub Base64URL.
storage/no-default-bucket	W usłudze storageBucket w konfiguracji nie ustawiono żadnego zasobnika.
storage/cannot-slice-blob	Zwykle występuje, gdy lokalny plik został zmieniony (usunięty, ponownie zapisany itp.). Spróbuj przesłać plik ponownie po sprawdzeniu, czy nie został zmieniony.
storage/server-file-wrong-size	Plik na urządzeniu klienta nie ma takiego samego rozmiaru jak plik odebrany przez serwer. Spróbuj przesłać go jeszcze raz.