"firebase.json — руководство по конфигурации Firebase Hosting, Functions и эмуляторов"

Зачем нужен firebase.json

firebase.json — главный конфигурационный файл проекта Firebase, который определяет поведение сервисов при локальной разработке и деплое. Это JSON-файл в корне репозитория, в котором вы указываете, какие ресурсы нужно деплоить (hosting, functions, firestore, database, storage и т.д.), правила, пред- и пост-скрипты и настройки эмуляторов.

Без корректного firebase.json вы рискуете:

• загружать не те файлы на Hosting;
• ломать SPA при обновлении страницы (404);
• неправильно перенаправлять запросы к Cloud Functions/Cloud Run;
• хранить лишнее в деплое или некорректно кешировать ресурсы.

Далее — разбор ключевых секций и конкретные примеры.

Общая структура и самые важные поля

Типичная структура (сокращённо):

```json { "hosting": { ... }, "functions": { ... }, "firestore": { ... }, "database": { ... }, "storage": { ... }, "emulators": { ... } } ```

Коротко по полям:

• hosting — конфигурация Firebase Hosting (публичная папка, rewrites, redirects, headers, ignore, cleanUrls и т.д.).
• functions — преднастройки для Cloud Functions (runtime, source, predeploy).
• firestore, database, storage — пути к файлам правил/индексов.
• emulators — порты и включение локальных эмуляторов.

По умолчанию в hosting часто включены: "public", "ignore" и "rewrites". Поле "public" обязательно для одного сайта.

Hosting: public, ignore, cleanUrls, trailingSlash

Ключевые опции:

• public — папка, откуда хостятся статические файлы, например "public" или "build".
• ignore — массив шаблонов для исключения файлов; обычно включает node_modules и скрытые файлы.
• cleanUrls — true удаляет .html из URL (пример: /about.html -> /about).
• trailingSlash — true|false управляет наличием слэша в конце URL.

Пример:

```json "hosting": { "public": "build", "ignore": ["firebase.json", "/.*", "/node_modules/"], "cleanUrls": true, "trailingSlash": false } ```

cleanUrls и trailingSlash применяются до rewrites/redirects — полезно для SEO и UX.

Rewrites, Redirects и Headers — как управлять трафиком

• redirects: статические перенаправления, указываете source, destination и HTTP-код (301, 302).
• rewrites: перенаправляют запросы на index.html (для SPA), на функции или на Cloud Run.
• headers: добавляют HTTP-заголовки по шаблонам путей (CSP, Cache-Control, HSTS и т.д.).

Примеры:

SPA-rewrite (один из самых распространённых случаев):

```json "rewrites": [ { "source": "/api/", "function": "api" }, { "source": "", "destination": "/index.html" } ] ```

Redirect с кодом 301:

```json "redirects": [ { "source": "/old-page", "destination": "/new-page", "type": 301 } ] ```

Cache-Control Header (статические ассеты на 1 год):

```json "headers": [ { "source": "/static/", "headers": [ { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" } ] } ] ```

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

Интеграция с Cloud Functions и Cloud Run

rewrites поддерживают перенаправления на:

• функцию: { "source": "/api/", "function": "api" }
• Cloud Run (serverless container): { "source": "/run/", "run": { "serviceId": "my-service", "region": "us-central1" } }

Пример mix hosting + functions:

```json "hosting": { "public": "dist", "rewrites": [ { "source": "/api/", "function": "api" }, { "source": "/run/", "run": { "serviceId": "web-worker", "region": "europe-west1" } }, { "source": "", "destination": "/index.html" } ] } ```

Для функций также можно указать predeploy-команды в раздел functions:

```json "functions": { "source": "functions", "predeploy": ["npm --prefix \"$RESOURCE_DIR\" run build"] } ```

Firestore, Realtime Database и Storage — где расположить правила

Указывайте файлы правил и индексы, чтобы при deploy Firebase применил их автоматически:

```json "firestore": { "rules": "firestore.rules", "indexes": "firestore.indexes.json" }, "database": { "rules": "database.rules.json" }, "storage": { "rules": "storage.rules" } ```

Это удобнее и безопаснее, чем ручной импорт правил через консоль.

Локальные эмуляторы (emulators) — полезно для разработки

Раздел emulators позволяет настроить порты и UI. Стандартные порты (часто используемые):

• hosting: 5000
• functions: 5001
• firestore: 8080
• realtime database: 9000
• auth: 9099
• pubsub: 8085
• storage: 9199
• emulators UI: 4000

Пример конфигурации:

```json "emulators": { "hosting": { "port": 5000 }, "functions": { "port": 5001 }, "firestore": { "port": 8080 }, "ui": { "enabled": true, "port": 4000 } } ```

Запуск: firebase emulators:start — этот файл позволит воспроизвести окружение локально, включая predeploy-скрипты и подключения.

Полный пример firebase.json

Полный пример, объединяющий основные элементы:

```json { "hosting": [ { "target": "web-app", "public": "build", "ignore": ["firebase.json", "/.*", "/node_modules/"], "cleanUrls": true, "trailingSlash": false, "headers": [ { "source": "/static/", "headers": [ { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" } ] }, { "source": "", "headers": [ { "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains; preload" } ] } ], "rewrites": [ { "source": "/api/", "function": "api" }, { "source": "", "destination": "/index.html" } ], "redirects": [ { "source": "/old", "destination": "/new", "type": 301 } ] } ], "functions": { "source": "functions", "predeploy": ["npm --prefix \"$RESOURCE_DIR\" run build"] }, "firestore": { "rules": "firestore.rules", "indexes": "firestore.indexes.json" }, "storage": { "rules": "storage.rules" }, "emulators": { "hosting": { "port": 5000 }, "functions": { "port": 5001 }, "firestore": { "port": 8080 }, "ui": { "enabled": true, "port": 4000 } } } ```

Обратите внимание: "target" используется для таргетного деплоя вместе с .firebaserc (firebase target:apply).

Частые ошибки и рекомендации

1. SPA-ошибка 404 при перезагрузке страницы: забудьте rewrite "**" -> "/index.html". Это вызывает большинство проблем. 2. Неправильные правила ignore: случайно исключили index.html или assets — файлы не будут загружены. 3. Predeploy-команды падают при CI — убедитесь, что зависимости установлены и скрипт корректный. В CI команды выполняются в каталоге $RESOURCE_DIR. 4. Неправильный Cache-Control: для часто изменяемых ресурсов ставьте короткий max-age (например, 60), для assets с content-hash — 31536000. 5. Конфиденциальные данные: в firebase.json обычно нет секретов. Не храните ключи/пароли в этом файле.

Команды деплоя и отладки

• Локально: firebase emulators:start
• Деплой всего: firebase deploy
• Деплой только hosting: firebase deploy --only hosting
• Деплой hosting для конкретного target: firebase deploy --only hosting:TARGET_NAME
• Деплой функций: firebase deploy --only functions

Если нужно увидеть, какие изменения будут задеплоены, используйте firebase deploy --only hosting --dry-run (если доступно) или сначала firebase deploy --only hosting --message "..." в CI.

Контроль версий и CI/CD

• Комментируйте predeploy в CI, если билд выполняется отдельным шагом.
• git-ignore не должен исключать firebase.json — он нужен для воспроизводимости деплоя.
• .firebaserc содержит alias и target mapping; вместе с firebase.json эти два файла полностью определяют поведение deploy.

Итог и чеклист

Перед деплоем проверьте:

• public указана правильно;
• ignore не удаляет нужные файлы;
• есть rewrite для SPA, если это одностраничное приложение;
• headers для безопасности и кеширования настроены;
• predeploy-скрипты работают локально и в CI;
• emulators настроены для локальной разработки (порты 5000/5001/8080/4000 и т.д.).