透過網頁版 Cloud Storage 上傳檔案

Cloud Storage for Firebase 可讓您輕鬆快速地將檔案上傳到 已提供 Cloud Storage 個值區 並由 Firebase 管理

注意： 根據預設，Cloud Storage 值區需要 Firebase Authentication 才能 對值區資料或檔案執行任何動作。你可以 變更Cloud Storage的Firebase Security Rules 允許未經驗證的存取因為 Firebase 和專案的預設值 App Engine 個應用程式共用這個值區，設定公開存取權可能會使 已上傳可公開存取的 App Engine 檔案。請務必限制 當您設定 Authentication 時，就能再次存取 Cloud Storage 值區。

注意： 以 Spark 方案專案來說，Firebase 會禁止上傳及託管某些項目 Windows 的可執行檔案類型 (使用 .exe 的檔案， .dll 和 .bat 擴充功能)，Android .apk 擴充功能) 和 Apple (.ipa 擴充功能)， Cloud Storage for Firebase和 Firebase Hosting。這項政策已存在 防止 YouTube 平台上的濫用行為Blaze 方案中的專案不會受到影響。 若需更多資訊，請參閲 這個常見問題。

上傳檔案

如要上傳檔案到 Cloud Storage，請先建立指向 檔案的完整路徑，包括檔案名稱。

Web

瞭解詳情 進一步瞭解可樹狀結構的模組化 Web API 升級 新增命名空間

import { getStorage, ref } from "firebase/storage";

// Create a root reference
const storage = getStorage();

// Create a reference to 'mountains.jpg'
const mountainsRef = ref(storage, 'mountains.jpg');

// Create a reference to 'images/mountains.jpg'
const mountainImagesRef = ref(storage, '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 
storage_upload_ref.js

Web

// 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 
upload-files.js

從 Blob 或 File 上傳

建立適當的參照後，接著要呼叫 uploadBytes() 方法。uploadBytes() 會透過 JavaScript 接收檔案 檔案和 Blob API 和上傳項目 至 Cloud Storage。

Web

瞭解詳情 進一步瞭解可樹狀結構的模組化 Web API 升級 新增命名空間

import { getStorage, ref, uploadBytes } from "firebase/storage";

const storage = getStorage();
const storageRef = ref(storage, 'some-child');

// 'file' comes from the Blob or File API
uploadBytes(storageRef, file).then((snapshot) => {
  console.log('Uploaded a blob or file!');
});
storage_upload_blob.js

Web

// 'file' comes from the Blob or File API
ref.put(file).then((snapshot) => {
  console.log('Uploaded a blob or file!');
});
upload-files.js

從 Byte 陣列上傳

除了 File 和 Blob 類型以外，uploadBytes() 也可以上傳 Uint8Array 到 Cloud Storage。

Web

瞭解詳情 進一步瞭解可樹狀結構的模組化 Web API 升級 新增命名空間

import { getStorage, ref, uploadBytes } from "firebase/storage";

const storage = getStorage();
const storageRef = ref(storage, 'some-child');

const bytes = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21]);
uploadBytes(storageRef, bytes).then((snapshot) => {
  console.log('Uploaded an array!');
});
storage_upload_bytes.js

Web

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

從字串上傳

如果無法使用 Blob、File 或 Uint8Array，您可以使用 使用 uploadString() 方法上傳原始、base64、base64url 或 data_url 編碼字串轉換成 Cloud Storage。

Web

瞭解詳情 進一步瞭解可樹狀結構的模組化 Web API 升級 新增命名空間

import { getStorage, ref, uploadString } from "firebase/storage";

const storage = getStorage();
const storageRef = ref(storage, 'some-child');

// Raw string is the default if no format is provided
const message = 'This is my message.';
uploadString(storageRef, message).then((snapshot) => {
  console.log('Uploaded a raw string!');
});

// Base64 formatted string
const message2 = '5b6p5Y+344GX44G+44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
uploadString(storageRef, message2, 'base64').then((snapshot) => {
  console.log('Uploaded a base64 string!');
});

// Base64url formatted string
const message3 = '5b6p5Y-344GX44G-44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
uploadString(storageRef, message3, 'base64url').then((snapshot) => {
  console.log('Uploaded a base64url string!');
});

// Data URL string
const message4 = 'data:text/plain;base64,5b6p5Y+344GX44G+44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
uploadString(storageRef, message4, 'data_url').then((snapshot) => {
  console.log('Uploaded a data_url string!');
});
storage_upload_string.js

Web

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

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

// Base64url formatted string
var message = '5b6p5Y-344GX44G-44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
ref.putString(message, 'base64url').then((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((snapshot) => {
  console.log('Uploaded a data_url string!');
});
upload-files.js

由於參照定義了檔案的完整路徑，因此請務必 檔案就會上傳至非空白路徑

新增檔案中繼資料

上傳檔案時，您也可以指定該檔案的中繼資料。 這項中繼資料包含一般檔案中繼資料屬性，例如 name、size、 和 contentType (通常稱為 MIME 類型)。Cloud Storage 會從 但如果您在中繼資料中指定 contentType，就會 會覆寫自動偵測的類型如未指定 contentType 中繼資料，且 檔案沒有副檔名，但預設值為 Cloud Storage 輸入 application/octet-stream。如要進一步瞭解檔案中繼資料，請參閱這篇文章 在「使用檔案中繼資料」一節中 專區。

Web

瞭解詳情 進一步瞭解可樹狀結構的模組化 Web API 升級 新增命名空間

import { getStorage, ref, uploadBytes } from "firebase/storage";

const storage = getStorage();
const storageRef = ref(storage, 'images/mountains.jpg');

// Create file metadata including the content type
/** @type {any} */
const metadata = {
  contentType: 'image/jpeg',
};

// Upload the file and metadata
const uploadTask = uploadBytes(storageRef, file, metadata);
storage_upload_metadata.js

Web

// 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);
upload-files.js

管理上傳項目

除了開始上傳之外，您還可以使用 pause()、resume() 和 cancel() 方法。撥打 pause() 或 resume() 會提高 pause 或 running 狀態變更。呼叫 cancel() 方法會導致上傳失敗並傳回錯誤 代表上傳作業已取消。

Web

瞭解詳情 進一步瞭解可樹狀結構的模組化 Web API 升級 新增命名空間

import { getStorage, ref, uploadBytesResumable } from "firebase/storage";

const storage = getStorage();
const storageRef = ref(storage, 'images/mountains.jpg');

// Upload the file and metadata
const uploadTask = uploadBytesResumable(storageRef, file);

// Pause the upload
uploadTask.pause();

// Resume the upload
uploadTask.resume();

// Cancel the upload
uploadTask.cancel();
storage_manage_uploads.js

Web

// 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();
upload-files.js

監控上傳進度

上傳時，上傳工作可能會在 state_changed 觀察器，例如：

事件類型	一般用量
running	這個事件會在工作開始或繼續上傳時觸發，且通常 與 pause 事件搭配使用大型適用 上傳這個事件可能會多次觸發進度更新。
pause	這個事件會在每次暫停上傳時觸發，通常用於 搭配 running 事件使用

事件發生時，系統會傳回 TaskSnapshot 物件。這張數據匯報 是事件發生時，工作的不可變動檢視畫面。 這個物件包含下列屬性：

屬性	類型	說明
bytesTransferred	Number	此時間已傳輸的位元組總數 已拍攝快照
totalBytes	Number	預計上傳的位元組總數。
state	firebase.storage.TaskState	上傳作業目前的狀態。
metadata	firebaseStorage.Metadata	上傳完成之前，中繼資料會傳送至伺服器。上傳影片後 完成後，伺服器傳回的中繼資料
task	firebaseStorage.UploadTask	這是一項工作快照，可以用來 `pause`、`resume` 或 `cancel` 工作。
ref	firebaseStorage.Reference	這項工作的參照。

狀態的變更，結合 TaskSnapshot 的屬性 讓使用者以簡單而強大的方式監控上傳事件。

Web

瞭解詳情 進一步瞭解可樹狀結構的模組化 Web API 升級 新增命名空間

import { getStorage, ref, uploadBytesResumable, getDownloadURL } from "firebase/storage";

const storage = getStorage();
const storageRef = ref(storage, 'images/rivers.jpg');

const uploadTask = uploadBytesResumable(storageRef, 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', 
  (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
    const progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100;
    console.log('Upload is ' + progress + '% done');
    switch (snapshot.state) {
      case 'paused':
        console.log('Upload is paused');
        break;
      case 'running':
        console.log('Upload is running');
        break;
    }
  }, 
  (error) => {
    // Handle unsuccessful uploads
  }, 
  () => {
    // Handle successful uploads on complete
    // For instance, get the download URL: https://firebasestorage.googleapis.com/...
    getDownloadURL(uploadTask.snapshot.ref).then((downloadURL) => {
      console.log('File available at', downloadURL);
    });
  }
);
storage_monitor_upload.js

Web

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', 
  (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;
    }
  }, 
  (error) => {
    // Handle unsuccessful uploads
  }, 
  () => {
    // Handle successful uploads on complete
    // For instance, get the download URL: https://firebasestorage.googleapis.com/...
    uploadTask.snapshot.ref.getDownloadURL().then((downloadURL) => {
      console.log('File available at', downloadURL);
    });
  }
);
upload-files.js

處理錯誤

導致上傳發生錯誤的原因有很多種，包括 本機檔案不存在，或使用者無權上傳 指定要上傳的檔案如要進一步瞭解錯誤，請前往 處理錯誤 一節。

完整範例

含有進度監控和錯誤處理機制的完整上傳示例 如下所示：

Web

瞭解詳情 進一步瞭解可樹狀結構的模組化 Web API 升級 新增命名空間

import { getStorage, ref, uploadBytesResumable, getDownloadURL } from "firebase/storage";

const storage = getStorage();

// Create the file metadata
/** @type {any} */
const metadata = {
  contentType: 'image/jpeg'
};

// Upload file and metadata to the object 'images/mountains.jpg'
const storageRef = ref(storage, 'images/' + file.name);
const uploadTask = uploadBytesResumable(storageRef, file, metadata);

// Listen for state changes, errors, and completion of the upload.
uploadTask.on('state_changed',
  (snapshot) => {
    // Get task progress, including the number of bytes uploaded and the total number of bytes to be uploaded
    const progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100;
    console.log('Upload is ' + progress + '% done');
    switch (snapshot.state) {
      case 'paused':
        console.log('Upload is paused');
        break;
      case 'running':
        console.log('Upload is running');
        break;
    }
  }, 
  (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;
    }
  }, 
  () => {
    // Upload completed successfully, now we can get the download URL
    getDownloadURL(uploadTask.snapshot.ref).then((downloadURL) => {
      console.log('File available at', downloadURL);
    });
  }
);
storage_upload_handle_error.js

Web

// 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'
  (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;
    }
  }, 
  (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;
    }
  }, 
  () => {
    // Upload completed successfully, now we can get the download URL
    uploadTask.snapshot.ref.getDownloadURL().then((downloadURL) => {
      console.log('File available at', downloadURL);
    });
  }
);
upload-files.js

上傳檔案後，我們接著來學習如何 下載 出發地：Cloud Storage。