處理 Android 中 Cloud Storage 的錯誤

有時計畫趕不上變化，可能會發生錯誤。

如有疑問，請檢查傳回的錯誤，並查看錯誤訊息內容。 下列程式碼顯示自訂錯誤處理常式的實作方式，可檢查 Cloud Storage 傳回的錯誤代碼和錯誤訊息。這類錯誤處理常式可以新增至 Cloud Storage API 中使用的各種物件 (例如 UploadTask 和 FileDownloadTask)。

Kotlin

internal inner class MyFailureListener : OnFailureListener {
    override fun onFailure(exception: Exception) {
        val errorCode = (exception as StorageException).errorCode
        val errorMessage = exception.message
        // test the errorCode and errorMessage, and handle accordingly
    }
}
StorageActivity.kt

Java

class MyFailureListener implements OnFailureListener {
    @Override
    public void onFailure(@NonNull Exception exception) {
        int errorCode = ((StorageException) exception).getErrorCode();
        String errorMessage = exception.getMessage();
        // test the errorCode and errorMessage, and handle accordingly
    }
}
StorageActivity.java

如果檢查錯誤訊息後，您Cloud Storage Security Rules允許執行動作，但仍無法修正錯誤，請前往支援頁面，告訴我們如何提供協助。

處理錯誤訊息

發生錯誤的原因有很多，包括檔案不存在、使用者沒有存取所需檔案的權限，或是使用者取消上傳檔案。

如要正確診斷問題並處理錯誤，請參閱下列完整清單，瞭解用戶端會引發的所有錯誤，以及這些錯誤的發生方式。這個表格中的錯誤代碼在 StorageException 類別中定義為整數常數。

程式碼 原因
ERROR_UNKNOWN 發生不明錯誤。
ERROR_OBJECT_NOT_FOUND 指定參照位置沒有物件。
ERROR_BUCKET_NOT_FOUND 未為「Cloud Storage」設定 bucket
ERROR_PROJECT_NOT_FOUND 尚未為 Cloud Storage 設定專案
ERROR_QUOTA_EXCEEDED 您已超過 Cloud Storage bucket 的配額。如果目前採用 Spark 定價方案，建議升級至即付即用的 Blaze 定價方案。如果目前採用 Blaze 定價方案，請與 Firebase 支援團隊聯絡。

重要事項：2025 年 10 月 1 日起，使用 Cloud Storage (包括預設 bucket) 時，必須採用 Blaze 定價方案。
ERROR_NOT_AUTHENTICATED 使用者未通過驗證，請驗證後再試一次。
ERROR_NOT_AUTHORIZED 使用者未經授權，無法執行要求動作，請檢查規則是否正確。
ERROR_RETRY_LIMIT_EXCEEDED 作業 (上傳、下載、刪除等) 的時間限制已超過上限。請再試一次。
ERROR_INVALID_CHECKSUM 用戶端上的檔案與伺服器收到的檔案總和檢查碼不符。請重新上傳。
ERROR_CANCELED 使用者已取消操作。

此外，如果嘗試使用無效網址呼叫 getReferenceFromUrl()，系統會擲回 IllegalArgumentException。上述方法的引數必須採用 gs://bucket/object 或 https://firebasestorage.googleapis.com/v0/b/bucket/o/object?token=<TOKEN> 格式。