Загрузка файлов в Firebase Storage с React

Загрузка файлов в Firebase Storage .jpg?w=1600&h=900&fit=crop)

Firebase Storage предоставляет простой способ хранения данных, созданных пользователями: изображений, видео и аудиофайлов. Он интегрируется с Firebase Authentication, что позволяет контролировать, кто имеет доступ к файлам. Storage автоматически масштабируется по мере роста объёма данных и легко сочетается с фронтенд-фреймворками, например с React.

Что вы получите в этом руководстве

Быстрая стартовая инструкция: создание React-приложения и подключение Firebase.
Рабочий пример компонента App.js с выбором файла, кнопкой загрузки и отображением прогресса.
Разъяснения по resumable-загрузкам, получению URL загруженного файла и сохранению ссылки.
Рекомендации по безопасности, структуре хранилища и тестированию.

Важно: примеры кода в статье рассчитаны на современный модульный импорт Firebase v9+ (modular SDK). Если вы используете старую версию Firebase, синтаксис будет отличаться.

1. Подготовка проекта

Создайте React-приложение при помощи create-react-app (локально):

npx create-react-app firebase-upload

Минимальный интерфейс — поле ввода для файла и кнопка для загрузки. Ниже приведён упрощённый компонент App.js, который мы постепенно дополним.

import { useState } from "react";

function App() {
  const [file, setFile] = useState("");

  function handleChange(event) {
    setFile(event.target.files[0]);
  }

  return (
    
      
      
    
  );
}

export default App;

Краткое пояснение: атрибут accept=”image/*” подсказывает диалоговому окну выбрать только изображения. Функция handleChange сохраняет выбранный файл в состояние.

2. Создайте проект Firebase и bucket

Создание проекта Firebase

Зайдите в консоль Firebase (console.firebase.google.com).
Нажмите Add project / Create a project и следуйте мастеру.
Назовите проект и нажмите Continue.

Форма создания проекта Firebase, запрос названия проекта

Отключите Google Analytics для простого тестового проекта, если он вам не нужен, и завершите создание.

Форма создания проекта Firebase с отключённой аналитикой Google

После создания нажмите на иконку web-приложения в обзоре проекта, чтобы зарегистрировать веб‑приложение.

Страница обзора проекта Firebase, кнопка регистрации веб-приложения

Сохраните конфигурационный объект Firebase — он понадобится для инициализации в приложении.

Создание Cloud Storage bucket

В консоли проекта перейдите в раздел Storage.

Обзор проекта Firebase, раздел Storage выделен

Нажмите Get Started, выберите режим тестирования (test mode) для разработки и укажите регион по умолчанию.

Страница конфигурации Firebase Storage при первоначальной настройке

После этого bucket будет готов для загрузки файлов.

3. Подключение Firebase к React

Установите Firebase SDK в папке проекта:

npm install firebase

Создайте файл src/firebaseConfig.js и инициализируйте приложение. Используйте конфигурацию, которую вы скопировали из консоли Firebase.

import { initializeApp } from "firebase/app";
import { getStorage } from "firebase/storage";

const firebaseConfig = {
  apiKey: "",
  authDomain: "",
  projectId: "",
  storageBucket: "",
  messagingSenderId: "",
  appId: "",
  measurementId: ""
};

const app = initializeApp(firebaseConfig);
const storage = getStorage(app);
export default storage;

Примечание: здесь используется экспорт по умолчанию (export default storage). В компонентах вы будете импортировать storage как default import.

4. Реализация загрузки с прогрессом

Добавим в App.js логику для загрузки, отображения прогресса, обработки ошибок и получения конечного URL файла.

import { useState } from "react";
import storage from "./firebaseConfig";
import { ref, uploadBytesResumable, getDownloadURL } from "firebase/storage";

function App() {
  const [file, setFile] = useState("");
  const [percent, setPercent] = useState(0);

  function handleChange(event) {
    setFile(event.target.files[0]);
  }

  const handleUpload = () => {
    if (!file) {
      alert("Please upload an image first!");
      return;
    }

    const storageRef = ref(storage, `/files/${file.name}`);

    const uploadTask = uploadBytesResumable(storageRef, file);

    uploadTask.on(
      "state_changed",
      (snapshot) => {
        const percent = Math.round((snapshot.bytesTransferred / snapshot.totalBytes) * 100);
        setPercent(percent);
      },
      (err) => {
        console.error(err);
        alert("Upload failed. Check console for details.");
      },
      () => {
        getDownloadURL(uploadTask.snapshot.ref).then((url) => {
          console.log("File available at: ", url);
          // Здесь можно сохранить url в базе данных
          alert("Upload complete. URL сохранён в консоли.");
        });
      }
    );
  };

  return (
    
      
      
      {percent} % done
    
  );
}

export default App;

Ключевые моменты:

uploadBytesResumable позволяет приостанавливать и возобновлять загрузку и предоставляет событие state_changed для отслеживания прогресса.
getDownloadURL возвращает публичный (или доступный по правилам) URL загруженного файла.

5. Что делать с URL после загрузки

В реальном приложении URL обычно сохраняют в базе данных (Firestore или Realtime Database) вместе с метаданными (ownerId, createdAt, mimeType, оригинальное имя файла). Это упрощает отображение списка файлов и управление доступом.

Пример хранения ссылки в Firestore (псевдокод):

// Сохранить URL и метаданные
import { getFirestore, collection, addDoc } from "firebase/firestore";
const db = getFirestore();
await addDoc(collection(db, "images"), {
  url: url,
  name: file.name,
  owner: auth.currentUser.uid,
  createdAt: new Date().toISOString()
});

6. Правила доступа и безопасность

По умолчанию в режимe test Firebase Storage открывает доступ. Для продакшена обязательно настройте security rules и интеграцию с Authentication. Простая практика — хранить файлы в папке, соответствующей uid пользователя:

Путь: /users/{uid}/files/{fileName}
Правило: чтение/запись разрешены только аутентифицированному пользователю с совпадающим uid.

Пример правила безопасности (без деталей, общее описание):

allow read, write: if request.auth != null && request.auth.uid == resourcePathUid

Важно: тестовый режим подходит только для разработки. Перед публикацией смените правила на ограничительные.

7. Лучшие практики и рекомендации

Именование файлов: избегайте пробелов и специальных символов. Добавляйте временную метку или уникальный идентификатор (UUID) для предотвращения конфликтов.
Метаданные: сохраняйте mimeType и размер файла.
Ограничения размера: валидируйте размер файла на клиенте и/или сервере.
Ограничение форматов: используйте accept и проверку MIME типа.
Обработка ошибок: показывайте пользователю понятные сообщения и предлагайте повторить загрузку.
Производительность: используйте CDN и правила кэширования для часто запрашиваемых файлов.

8. Отслеживание прогресса и UX

Показывайте прогресс загрузки (в процентах или полосе прогресса). При больших файлах добавьте функционал приостановки и возобновления. В мобильных сетях предусмотрите тайм-ауты и повторные попытки.

9. Отладка и тестирование

Тестируйте с файлами разных размеров и типов.
Проверяйте поведение при потере сети и её восстановлении.
Убедитесь, что правила безопасности не мешают легитимным пользователям.

Критерии приёмки

Файл выбирается через диалог и сохраняется в стейт.
При нажатии Upload начинается загрузка и отображается процент прогресса.
После завершения в консоль выводится корректный URL, и он доступен в браузере с учётом правил доступа.
Ошибки ясно отображаются пользователю.

10. Роль‑ориентированные чек‑листы

Разработчик:

Подключил SDK и настроил storageRef.
Реализовал обработку progress и ошибок.
Валидирует тип и размер файла.

DevOps / Администратор:

Настроил bucket в нужном регионе.
Проверил правила безопасности для продакшна.
Настроил мониторинг и лимиты (если нужно).

Product / PM:

Определил допустимые форматы и максимальный размер файла.
Утвердил правила хранения и время жизни файлов.

11. Мини‑методология развертывания

Разработка: использовать test mode и локальный build.
Тестирование: проверить кейсы загрузки, ошибки сети, безопасность.
Рецензирование правил безопасности и аудита доступа.
Перевод bucket в рабочий режим с ограничительными правилами.
Мониторинг после релиза.

12. Частые ошибки и как их решать

Ошибка: “Permission denied” — проверьте security rules и аутентификацию пользователя.
Ошибка: загрузка прерывается — проверьте сетевые тайм‑аута и повторные попытки.
Ошибка: неправильный MIME — проверьте accept и заголовки файла.

13. Дополнительные опции и альтернативы

Использовать Cloud Functions для генерации защищённых ссылок или обработки изображений после загрузки (например, создание превью).
Использовать сторонние решения (S3, Cloudinary) если нужна дополнительная функциональность: преобразование изображений, оптимизация и более гибкая тарификация.

14. Тесты и критерии приёмки

Тест #1: загрузить файл 100KB — ожидаемый результат: прогресс достигает 100%, URL доступен.
Тест #2: попытка загрузить без выбора файла — ожидаемый результат: пользователь получает подсказку.
Тест #3: загрузка большого файла (несколько сотен МБ) — ожидаемый результат: загрузка проходит устойчиво либо корректно прерывается и можно возобновить.

15. Сводка

Firebase Storage — удобный инструмент для хранения пользовательских файлов и прост в интеграции с React. Ключевые элементы успешной реализации: корректная инициализация SDK, использование uploadBytesResumable для контроля прогресса, безопасная структура хранения и внимательная настройка security rules.

Важно: перед выпуском в продакшен обязательно проверить правила доступа, масштабирование и политику хранения.

Ключевые шаги:

Создать Firebase-проект и bucket.
Подключить Firebase в приложении и инициализировать storage.
Реализовать загрузку с прогрессом и обработкой ошибок.
Сохранить URL и метаданные для дальнейшего использования.

Дополнительные ресурсы и материалы по теме можно найти в официальной документации Firebase Storage (console.firebase.google.com и docs.firebase.google.com).