معالجة الأخطاء في Cloud Storage على Flutter

في بعض الأحيان، قد لا تسير الأمور كما هو مخطّط لها أثناء إنشاء تطبيق، وقد يؤدي ذلك إلى حدوث خطأ.

في حال الشك، يمكنك رصد الاستثناء الذي تطلقه الدالة والاطّلاع على ما تفيد به رسالة الخطأ.

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}");
}

ملاحظة: تتطلّب حزمة Cloud Storage for Firebase تلقائيًا من Firebase Authentication تنفيذ أي إجراء على بيانات الحزمة أو ملفاتها. يمكنك تغيير Firebase Security Rules إلى Cloud Storage لالسماح بالوصول غير المعتمَد في حالات معيّنة. ومع ذلك، في معظم الحالات، ننصحك بشدة بحظر الوصول وإعداد قواعد أمان صارمة (خاصةً للتطبيقات العلنية). يُرجى العِلم أنّه في حال استخدام Google App Engine وامتلاك حزمة Cloud Storage تلقائية بتنسيق اسم *.appspot.com، قد تحتاج إلى مراعاة تأثير قواعد الأمان في الوصول إلى ملفات App Engine.

معالجة رسائل الخطأ

هناك عدد من الأسباب التي قد تؤدي إلى حدوث أخطاء، بما في ذلك عدم توفّر الملف أو عدم توفّر إذن للمستخدم بالوصول إلى الملف المطلوب أو إلغاء المستخدم لتحميل الملف.

لتشخيص المشكلة ومعالجة الخطأ بشكل صحيح، إليك قائمة كاملة ب كل الأخطاء التي سيُبلغ عنها العميل وكيفية حدوثها.

الرمز	الوصف
storage/unknown	حدث خطأ غير معروف.
storage/object-not-found	لا يتوفّر أي عنصر في المرجع المطلوب.
storage/bucket-not-found	لم يتم إعداد حزمة في Cloud Storage
storage/project-not-found	لم يتم إعداد أي مشروع في Cloud Storage
storage/quota-exceeded	تم تجاوز الحصة في حزمة Cloud Storage. إذا كنت مشتركًا في خطة أسعار Spark، ننصحك بالترقية إلى خطة أسعار Blaze المستندة إلى الدفع عند الاستخدام. إذا كنت مشتركًا في خطة أسعار Blaze، يُرجى التواصل مع فريق دعم Firebase. ملاحظة مهمة: اعتبارًا من 1 تشرين الأول (أكتوبر) 2025، ستكون خطة أسعار Blaze مطلوبة لاستخدام Cloud Storage، حتى الحِزم التلقائية.
storage/unauthenticated	لم تتم مصادقة المستخدم، يُرجى المصادقة وإعادة المحاولة.
storage/unauthorized	المستخدم غير مفوَّض بتنفيذ الإجراء المطلوب، لذا يُرجى التحقّق من قواعد الأمان للتأكّد من صحتها.
storage/retry-limit-exceeded	تم تجاوز الحد الأقصى للوقت المسموح به لتنفيذ عملية (تحميل أو تنزيل أو حذف أو غير ذلك). يُرجى محاولة التحميل مرة أخرى.
storage/invalid-checksum	لا يتطابق الملف على جهاز العميل مع القيمة المحسوبة للملف الذي تلقّاه الخادم. يُرجى محاولة التحميل مرة أخرى.
storage/canceled	ألغى المستخدِم العملية.
storage/invalid-event-name	تم تقديم اسم حدث غير صالح. يجب أن يكون أحد القيم التالية: [running أو progress أو pause]
storage/invalid-url	تم تقديم عنوان URL غير صالح إلى refFromURL(). يجب أن يكون على الشكل التالي: gs://bucket/object أو https://firebasestorage.googleapis.com/v0/b/bucket/o/object?token=<TOKEN>
storage/invalid-argument	يجب أن تكون الوسيطة التي تم تمريرها إلى put() صفيف File أو Blob أو UInt8. يجب أن تكون الوسيطة التي تم تمريرها إلى putString() سلسلة ثنائية أو Base64 أو Base64URL.
storage/no-default-bucket	لم يتم ضبط أي حزمة في ملف الإعدادات الخاص بخاصية storageBucket.
storage/cannot-slice-blob	يحدث هذا عادةً عندما يتغيّر الملف على الجهاز (يتم حذفه أو حفظه مرة أخرى أو غير ذلك). حاوِل تحميل الملف مرة أخرى بعد التأكّد من أنّه لم يتغيّر.
storage/server-file-wrong-size	لا يتطابق حجم الملف على جهاز العميل مع حجم الملف الذي تلقّاه الخادم. يُرجى محاولة التحميل مرة أخرى.