从 Cloud Storage 下载文件 (Flutter)

Cloud Storage for Firebase 可让您快速轻松地从 Firebase 提供和管理的 Cloud Storage 存储桶中下载文件。

注意：默认情况下，需要经过 Firebase Authentication 身份验证才能对 Cloud Storage 存储桶中的数据或文件执行操作。您可以更改 Cloud Storage 的 Firebase 安全规则，允许未经身份验证的访问。由于 Firebase 会与项目的默认 App Engine 应用共用此存储桶，因此配置公开访问权限可能会使新上传的 App Engine 文件也可被公开访问。设置 Authentication 时，请务必重新限制对 Cloud Storage 存储桶的访问权限。

创建引用

如需下载某个文件，请先为要下载的文件创建一个 Cloud Storage 引用。

您可以通过将子路径附加到 Cloud Storage 存储桶的根目录来创建引用，也可以根据指向 Cloud Storage 中的对象的现有 gs:// 或 https:// 网址创建引用。

// Create a storage reference from our app
final storageRef = FirebaseStorage.instance.ref();

// Create a reference with an initial file path and name
final pathReference = storageRef.child("images/stars.jpg");

// Create a reference to a file from a Google Cloud Storage URI
final gsReference =
    FirebaseStorage.instance.refFromURL("gs://YOUR_BUCKET/images/stars.jpg");

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
final httpsReference = FirebaseStorage.instance.refFromURL(
    "https://firebasestorage.googleapis.com/b/YOUR_BUCKET/o/images%20stars.jpg");

下载文件

有了引用之后，您便可以调用 getData() 或 getStream() 方法从 Cloud Storage 下载文件。如果您希望使用其他的库下载文件，则可以使用 getDownloadUrl() 方法获取下载网址。

下载至内存

您可以使用 getData() 方法将文件下载到 UInt8List。这是最简单的文件下载方法，但它必须将文件的全部内容加载到内存中。如果您请求下载的文件大于应用的可用内存，应用将会崩溃。为防止出现内存问题，可以为 getData() 设置一个下载字节数上限参数。请将该上限设为您知道应用可以处理的大小，或者使用其他下载方法。

final islandRef = storageRef.child("images/island.jpg");

try {
  const oneMegabyte = 1024 * 1024;
  final Uint8List? data = await islandRef.getData(oneMegabyte);
  // Data for "images/island.jpg" is returned, use this as needed.
} on FirebaseException catch (e) {
  // Handle any errors.
}

下载至本地文件

writeToFile() 方法可将文件直接下载至本地设备。如果用户希望离线时可以访问文件或希望在不同的应用中共享文件，请使用这种方法。writeToFile() 会返回一个 DownloadTask，您可以使用它来管理下载并监控下载状态。

final islandRef = storageRef.child("images/island.jpg");

final appDocDir = await getApplicationDocumentsDirectory();
final filePath = "${appDocDir.absolute}/images/island.jpg";
final file = File(filePath);

final downloadTask = islandRef.writeToFile(file);
downloadTask.snapshotEvents.listen((taskSnapshot) {
  switch (taskSnapshot.state) {
    case TaskState.running:
      // TODO: Handle this case.
      break;
    case TaskState.paused:
      // TODO: Handle this case.
      break;
    case TaskState.success:
      // TODO: Handle this case.
      break;
    case TaskState.canceled:
      // TODO: Handle this case.
      break;
    case TaskState.error:
      // TODO: Handle this case.
      break;
  }
});

通过网址下载数据

如果您已经有了基于网址的下载基础架构，或者只需要一个网址用于共享，可通过对 Cloud Storage 引用调用 getDownloadURL() 方法来获取文件的下载网址。

final imageUrl =
    await storageRef.child("users/me/profile.png").getDownloadURL();

处理错误

导致下载出错的原因有很多，包括文件不存在，或者用户不具备访问相应文件的权限。如需了解有关错误的详细信息，请参阅文档的处理错误部分。

完整示例

包含错误处理的下载完整示例如下：

final islandRef = storageRef.child("images/island.jpg");

final appDocDir = await getApplicationDocumentsDirectory();
final filePath = "${appDocDir.absolute}/images/island.jpg";
final file = File(filePath);

final downloadTask = islandRef.writeToFile(file);
downloadTask.snapshotEvents.listen((taskSnapshot) {
  switch (taskSnapshot.state) {
    case TaskState.running:
      // TODO: Handle this case.
      break;
    case TaskState.paused:
      // TODO: Handle this case.
      break;
    case TaskState.success:
      // TODO: Handle this case.
      break;
    case TaskState.canceled:
      // TODO: Handle this case.
      break;
    case TaskState.error:
      // TODO: Handle this case.
      break;
  }
});

对于存储在 Cloud Storage 中的文件，您还可以获取和更新元数据。