处理 Cloud Storage 错误 (Android)

错误时有发生。

如有疑问，请检查返回的错误，并查看错误消息的内容。下面的代码显示了一个自定义错误处理程序实现，它会检查 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 配置存储桶
ERROR_PROJECT_NOT_FOUND 没有为 Cloud Storage 配置项目
ERROR_QUOTA_EXCEEDED 已超过您的 Cloud Storage 存储桶的配额。如果您使用的是 Spark 定价方案，不妨考虑升级到随用随付 Blaze 定价方案。如果您已采用 Blaze 定价方案，请与 Firebase 支持团队联系。

重要提示：自 2026 年 2 月 2 日起（最早），必须采用 Blaze 定价方案才能使用 Cloud Storage，即使是默认存储桶也是如此。
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>