在网页上上传文件

Cloud Storage 可让开发者向由 Firebase 提供和管理的 Google Cloud Storage 存储分区快速轻松地上传文件。

由于默认的 Google App Engine 应用和 Firebase 共用此存储分区,因此将访问权限配置为公开可能会使新上传的 App Engine 文件也可被公开访问。在设置身份验证时,请务必重新限制对 Cloud Storage 存储分区的访问权限。

上传文件

要将文件上传到 Cloud Storage,首先要创建对文件的完整路径(包括文件名)的引用。

// Create a root reference
var storageRef = firebase.storage().ref();

// Create a reference to 'mountains.jpg'
var mountainsRef = storageRef.child('mountains.jpg');

// Create a reference to 'images/mountains.jpg'
var mountainImagesRef = storageRef.child('images/mountains.jpg');

// While the file names are the same, the references point to different files
mountainsRef.name === mountainImagesRef.name            // true
mountainsRef.fullPath === mountainImagesRef.fullPath    // false

通过 BlobFile 上传

创建合适的引用后,调用 put() 方法。 put() 通过 JavaScript FileBlob API 接受文件并将它们上传至 Cloud Storage。

var file = ... // use the Blob or File API
ref.put(file).then(function(snapshot) {
  console.log('Uploaded a blob or file!');
});

通过字节型数组上传

除了 FileBlob 类型外,put() 也可以将 Uint8Array 上传至 Cloud Storage。

// Uint8Array
var bytes = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21]);
ref.put(bytes).then(function(snapshot) {
  console.log('Uploaded an array!');
});

通过字符串上传

如果无法使用 BlobFileUint8Array,您可以使用 putString() 方法将一个原始 base64base64urldata_url 编码的字符串上传至 Cloud Storage。

// Raw string is the default if no format is provided
var message = 'This is my message.';
ref.putString(message).then(function(snapshot) {
  console.log('Uploaded a raw string!');
});

// Base64 formatted string
var message = '5b6p5Y+344GX44G+44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
ref.putString(message, 'base64').then(function(snapshot) {
  console.log('Uploaded a base64 string!');
});

// Base64url formatted string
var message = '5b6p5Y-344GX44G-44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
ref.putString(message, 'base64url').then(function(snapshot) {
  console.log('Uploaded a base64url string!');
});

// Data URL string
var message = 'data:text/plain;base64,5b6p5Y+344GX44G+44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
ref.putString(message, 'data_url').then(function(snapshot) {
  console.log('Uploaded a data_url string!');
});

put()putString() 均会返回 UploadTask,您可以将其用作 Promise 或用于管理和监测上传的状态。

由于引用定义了文件的完整路径,因此请确保您会将文件上传至非空路径。

添加文件元数据

上传文件时,您还可以指定该文件的元数据。这些元数据包括常见的文件元数据属性,如 namesizecontentType(通常称为 MIME 类型)。在文件存储在磁盘上的情况下,Cloud Storage 会利用文件的扩展名自动推断内容类型,但如果您在元数据中指定了 contentType,则指定的内容类型会覆盖自动检测到的类型。如果未指定 contentType 元数据,且文件没有文件扩展名,则 Cloud Storage 默认类型为 application/octet-stream。如需详细了解文件元数据,请参阅使用文件元数据部分。

// Create file metadata including the content type
var metadata = {
  contentType: 'image/jpeg',
};

// Upload the file and metadata
var uploadTask = storageRef.child('images/mountains.jpg').put(file, metadata);

管理上传

除了启动上传外,您可以使用 pause()resume()cancel() 方法暂停、恢复和取消上传。调用 pause()resume() 会引发 pauserunning 状态变化。调用 cancel() 方法会导致上传失败,并返回表示上传已取消的错误。

// Upload the file and metadata
var uploadTask = storageRef.child('images/mountains.jpg').put(file);

// Pause the upload
uploadTask.pause();

// Resume the upload
uploadTask.resume();

// Cancel the upload
uploadTask.cancel();

监控上传进度

上传时,上传任务可能会在 state_changed 观察者中引发进度事件,如:

事件类型 典型用法
running 此事件在任务开始或恢复上传时触发,且通常与 pause 事件结合使用。
progress 每次向 Cloud Storage 上传数据时,此事件都会触发,并且可用于为上传进度指示器提供显示数据。
pause 每次上传被暂停时,此事件都会触发,且通常与 running 事件结合使用。

发生某个事件时,系统将传回 TaskSnapshot 对象。此快照是事件发生时任务的视图,该视图不可改变。 此对象包含以下属性:

属性 类型 说明
bytesTransferred Number 截取快照时已传输的总字节数。
totalBytes Number 期望上传的总字节数。
state firebase.storage.TaskState 上传的当前状态。
metadata firebaseStorage.Metadata 上传完成前,表示已发送到服务器的元数据。上传完成后,表示服务器发回的元数据。
task firebaseStorage.UploadTask 快照所对应的任务,可用于“暂停”、“恢复”或“取消”任务。
ref firebaseStorage.Reference 此任务的来源引用。

将这些状态变化与 TaskSnapshot 的属性相结合,即可为监控上传事件提供一种简单而又强大的方法。

var uploadTask = storageRef.child('images/rivers.jpg').put(file);

// Register three observers:
// 1. 'state_changed' observer, called any time the state changes
// 2. Error observer, called on failure
// 3. Completion observer, called on successful completion
uploadTask.on('state_changed', function(snapshot){
  // Observe state change events such as progress, pause, and resume
  // Get task progress, including the number of bytes uploaded and the total number of bytes to be uploaded
  var progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100;
  console.log('Upload is ' + progress + '% done');
  switch (snapshot.state) {
    case firebase.storage.TaskState.PAUSED: // or 'paused'
      console.log('Upload is paused');
      break;
    case firebase.storage.TaskState.RUNNING: // or 'running'
      console.log('Upload is running');
      break;
  }
}, function(error) {
  // Handle unsuccessful uploads
}, function() {
  // Handle successful uploads on complete
  // For instance, get the download URL: https://firebasestorage.googleapis.com/...
  uploadTask.snapshot.ref.getDownloadURL().then(function(downloadURL) {
    console.log('File available at', downloadURL);
  });
});

错误处理

导致上传时出现错误的原因有很多,包括本地文件不存在,或者用户不具备上传所需文件的权限。如需了解有关错误的详细信息,请参阅文档的处理错误部分。

完整示例

下面是一个包含进度监控和错误处理的完整上传示例:

// File or Blob named mountains.jpg
var file = ...

// Create the file metadata
var metadata = {
  contentType: 'image/jpeg'
};

// Upload file and metadata to the object 'images/mountains.jpg'
var uploadTask = storageRef.child('images/' + file.name).put(file, metadata);

// Listen for state changes, errors, and completion of the upload.
uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, // or 'state_changed'
  function(snapshot) {
    // Get task progress, including the number of bytes uploaded and the total number of bytes to be uploaded
    var progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100;
    console.log('Upload is ' + progress + '% done');
    switch (snapshot.state) {
      case firebase.storage.TaskState.PAUSED: // or 'paused'
        console.log('Upload is paused');
        break;
      case firebase.storage.TaskState.RUNNING: // or 'running'
        console.log('Upload is running');
        break;
    }
  }, function(error) {

  // A full list of error codes is available at
  // https://firebase.google.com/docs/storage/web/handle-errors
  switch (error.code) {
    case 'storage/unauthorized':
      // User doesn't have permission to access the object
      break;

    case 'storage/canceled':
      // User canceled the upload
      break;

    ...

    case 'storage/unknown':
      // Unknown error occurred, inspect error.serverResponse
      break;
  }
}, function() {
  // Upload completed successfully, now we can get the download URL
  uploadTask.snapshot.ref.getDownloadURL().then(function(downloadURL) {
    console.log('File available at', downloadURL);
  });
});

现在您已经上传了文件,接下来,我们将学习如何从 Cloud Storage 下载文件

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面