پیکربندی رفتار میزبانی

با Firebase Hosting ، می‌توانید رفتار میزبانی سفارشی را برای درخواست‌های سایت خود پیکربندی کنید.

چه چیزی را می توانید برای Hosting پیکربندی کنید؟

  • مشخص کنید که کدام فایل ها را در فهرست پروژه محلی خود می خواهید در Firebase Hosting مستقر کنید. یاد بگیرید چگونه.

  • ارائه یک صفحه سفارشی 404/Not Found. یاد بگیرید چگونه.

  • redirects برای صفحاتی که منتقل یا حذف کرده اید تنظیم کنید. یاد بگیرید چگونه.

  • rewrites برای هر یک از این اهداف تنظیم کنید:

  • headers را اضافه کنید تا اطلاعات اضافی در مورد یک درخواست یا پاسخ ارسال شود، مانند اینکه مرورگرها چگونه باید صفحه و محتوای آن را مدیریت کنند (احراز هویت، ذخیره سازی، رمزگذاری و غیره). یاد بگیرید چگونه.

  • بازنویسی های بین المللی (i18n) را برای ارائه محتوای خاص بر اساس ترجیح زبان و/یا کشور کاربر تنظیم کنید. یاد بگیرید چگونه (صفحه مختلف).

پیکربندی Hosting خود را کجا تعریف می کنید؟

شما پیکربندی Firebase Hosting خود را در فایل firebase.json خود تعریف می کنید. هنگامی که فرمان firebase init را اجرا می کنید، Firebase به طور خودکار فایل firebase.json شما را در ریشه دایرکتوری پروژه شما ایجاد می کند.

می‌توانید یک نمونه کامل از پیکربندی firebase.json (که فقط Firebase Hosting را پوشش می‌دهد) در پایین این صفحه پیدا کنید. توجه داشته باشید که یک فایل firebase.json می‌تواند شامل پیکربندی‌هایی برای سایر سرویس‌های Firebase نیز باشد.

با استفاده از Hosting REST API می توانید محتوای firebase.json مستقر شده را بررسی کنید.

ترتیب اولویت پاسخ های Hosting

گزینه های مختلف پیکربندی Firebase Hosting که در این صفحه توضیح داده شده است گاهی اوقات ممکن است با هم همپوشانی داشته باشند. اگر تضاد وجود داشته باشد، Hosting پاسخ خود را با استفاده از ترتیب اولویت زیر تعیین می کند:

  1. فضاهای نام رزرو شده که با یک بخش مسیر /__/* شروع می شوند
  2. تغییر مسیرهای پیکربندی شده
  3. محتوای ثابت با تطابق دقیق
  4. بازنویسی های پیکربندی شده
  5. صفحه سفارشی 404
  6. صفحه پیش فرض 404

اگر از بازنویسی‌های i18n استفاده می‌کنید، ترتیب تطابق دقیق و اولویت رسیدگی به 404 برای مطابقت با محتوای i18n شما گسترش می‌یابد.

مشخص کنید که کدام فایل ها مستقر شوند

ویژگی‌های پیش‌فرض - public و ignore - موجود در فایل firebase.json پیش‌فرض، تعریف می‌کنند که کدام فایل‌ها در فهرست پروژه شما باید در پروژه Firebase شما مستقر شوند.

پیکربندی پیش فرض hosting در یک فایل firebase.json به شکل زیر است:

"hosting": {
  "public": "public",  // the only required attribute for Hosting
  "ignore": [
    "firebase.json",
    "**/.*",
    "**/node_modules/**"
  ]
}

عمومی

مورد نیاز
مشخصه public مشخص می کند که کدام دایرکتوری در Firebase Hosting مستقر شود. مقدار پیش‌فرض دایرکتوری با نام public است، اما می‌توانید مسیر هر دایرکتوری را تا زمانی که در فهرست پروژه شما وجود دارد، مشخص کنید.

زیر نام پیش فرض مشخص شده دایرکتوری برای استقرار است:

"hosting": {
  "public": "public"

  // ...
}

می توانید مقدار پیش فرض را به دایرکتوری که می خواهید استقرار دهید تغییر دهید:

"hosting": {
  "public": "dist/app"

  // ...
}

نادیده گرفتن

اختیاری
ویژگی ignore فایل هایی را که در هنگام استقرار نادیده گرفته می شوند را مشخص می کند. می تواند globs را به همان روشی که Git با .gitignore اداره می کند، بگیرد.

مقادیر زیر مقادیر پیش‌فرض برای نادیده گرفتن فایل‌ها هستند:

"hosting": {
  // ...

  "ignore": [
    "firebase.json",  // the Firebase configuration file (the file described on this page)
    "**/.*",  // files with a leading period should be hidden from the system
    "**/node_modules/**"  // contains dependencies used to create your site but not run it
  ]
}

یک صفحه 404/Not Found را سفارشی کنید

اختیاری
وقتی کاربر سعی می‌کند به صفحه‌ای که وجود ندارد دسترسی پیدا کند، می‌توانید خطای سفارشی 404 Not Found را ارائه کنید.

یک فایل جدید در فهرست public پروژه خود ایجاد کنید، نام آن را 404.html بگذارید، سپس محتوای سفارشی 404 Not Found خود را به فایل اضافه کنید.

اگر مرورگر خطای 404 Not Found را در دامنه یا زیر دامنه شما ایجاد کند، Firebase Hosting محتوای این صفحه سفارشی 404.html را نمایش می دهد.

تغییر مسیرها را پیکربندی کنید

اختیاری
اگر صفحه‌ای را جابه‌جا کرده‌اید، از تغییر مسیر URL برای جلوگیری از شکستن لینک‌ها استفاده کنید یا URL‌ها را کوتاه کنید. برای مثال، می‌توانید مرورگر را از example.com/team به example.com/about.html هدایت کنید.

با ایجاد یک ویژگی redirects که حاوی آرایه ای از اشیاء است (به نام "قوانین تغییر مسیر") تغییر مسیرهای URL را مشخص کنید. در هر قانون، یک الگوی URL را مشخص کنید که اگر با مسیر URL درخواست مطابقت داشته باشد، Hosting تحریک می کند تا با تغییر مسیر به URL مقصد مشخص شده پاسخ دهد.

در اینجا ساختار اصلی برای یک ویژگی redirects آمده است. این مثال با ایجاد یک درخواست جدید به /bar ، درخواست ها را به /foo هدایت می کند.

"hosting": {
  // ...

  // Returns a permanent redirect to "/bar" for requests to "/foo" (but not "/foo/**")
  "redirects": [ {
    "source": "/foo",
    "destination": "/bar",
    "type": 301
  } ]
}

ویژگی redirects شامل آرایه ای از قوانین تغییر مسیر است که در آن هر قانون باید فیلدهای جدول زیر را شامل شود.

Firebase Hosting source یا مقدار regex را با تمام مسیرهای URL در شروع هر درخواست مقایسه می کند (قبل از اینکه مرورگر تعیین کند که آیا یک فایل یا پوشه در آن مسیر وجود دارد یا خیر). اگر مطابقت پیدا شد، سرور اصلی Firebase Hosting یک پاسخ تغییر مسیر HTTPS را ارسال می‌کند و به مرورگر می‌گوید یک درخواست جدید در URL destination ارسال کند.

میدان توضیحات
redirects
source (توصیه می شود)
یا regex

یک الگوی URL که اگر با URL درخواست اولیه مطابقت داشته باشد، Hosting برای اعمال تغییر مسیر تحریک می کند

  • از source برای تعیین یک glob استفاده کنید (توصیه می شود) .
  • از regex برای تعیین یک عبارت منظم RE2 استفاده کنید.
destination

یک URL ثابت که در آن مرورگر باید درخواست جدیدی ارائه کند

این URL می تواند یک مسیر نسبی یا مطلق باشد.

type

کد پاسخ HTTPS

  • از یک نوع 301 برای "انتقال دائمی" استفاده کنید
  • از یک نوع 302 برای «یافت» استفاده کنید (تغییر مسیر موقت)

بخش های URL را برای تغییر مسیرها ضبط کنید

اختیاری
گاهی اوقات، ممکن است لازم باشد بخش‌های خاصی از الگوی URL یک قانون تغییر مسیر (مقدار source یا regex ) را ضبط کنید، سپس دوباره از این بخش‌ها در مسیر destination قانون استفاده کنید.

بازنویسی ها را پیکربندی کنید

اختیاری
از یک بازنویسی برای نمایش محتوای یکسان برای چندین URL استفاده کنید. بازنویسی ها به ویژه در تطبیق الگو مفید هستند، زیرا می توانید هر URL را که با الگو مطابقت دارد بپذیرید و اجازه دهید کد سمت مشتری تصمیم بگیرد که چه چیزی را نمایش دهد.

همچنین می‌توانید از بازنویسی‌ها برای پشتیبانی از برنامه‌هایی که از HTML5 pushState برای پیمایش استفاده می‌کنند، استفاده کنید. هنگامی که یک مرورگر سعی می کند یک مسیر URL را باز کند که با الگوی URL source یا regex مشخص شده مطابقت دارد، به جای آن، محتوای فایل در URL destination به مرورگر داده می شود.

با ایجاد یک ویژگی rewrites که حاوی آرایه‌ای از اشیاء است (به نام «قوانین بازنویسی») بازنویسی‌های URL را مشخص کنید. در هر قانون، یک الگوی URL را مشخص کنید که اگر با مسیر URL درخواست مطابقت داشته باشد، Hosting فعال می‌کند تا به گونه‌ای پاسخ دهد که گویی URL مقصد مشخص شده به سرویس داده شده است.

در اینجا ساختار اصلی یک ویژگی rewrites است. این مثال index.html را برای درخواست هایی به فایل ها یا دایرکتوری هایی که وجود ندارند ارائه می کند.

"hosting": {
  // ...

  // Serves index.html for requests to files or directories that do not exist
  "rewrites": [ {
    "source": "**",
    "destination": "/index.html"
  } ]
}

ویژگی rewrites حاوی آرایه‌ای از قوانین بازنویسی است که هر قانون باید شامل فیلدهای جدول زیر باشد.

Firebase Hosting تنها زمانی قانون بازنویسی را اعمال می‌کند که فایل یا دایرکتوری در مسیر URL وجود نداشته باشد که با source مشخص شده یا الگوی URL regex مطابقت داشته باشد. هنگامی که یک درخواست یک قانون بازنویسی را راه اندازی می کند، مرورگر محتوای واقعی فایل destination مشخص شده را به جای تغییر مسیر HTTP برمی گرداند.

میدان توضیحات
rewrites
source (توصیه می شود)
یا regex

یک الگوی URL که اگر با URL درخواست اولیه مطابقت داشته باشد، Hosting تحریک می کند تا بازنویسی را اعمال کند

  • از source برای تعیین یک glob استفاده کنید (توصیه می شود) .
  • از regex برای تعیین یک عبارت منظم RE2 استفاده کنید.
destination

یک فایل محلی که باید وجود داشته باشد

این URL می تواند یک مسیر نسبی یا مطلق باشد.

درخواست های مستقیم به یک تابع

می توانید rewrites برای ارائه یک تابع از URL Firebase Hosting استفاده کنید. مثال زیر گزیده ای از ارائه محتوای پویا با استفاده از Cloud Functions است.

به عنوان مثال، برای هدایت همه درخواست ها از صفحه /bigben در سایت Hosting خود برای اجرای تابع bigben :

"hosting": {
  // ...

  // Directs all requests from the page `/bigben` to execute the `bigben` function
  "rewrites": [ {
    "source": "/bigben",
    "function": {
      "functionId": "bigben",
      "region": "us-central1"  // optional (see note below)
      "pinTag": true           // optional (see note below)
    }
  } ]
}

پس از افزودن این قانون بازنویسی و استقرار در Firebase (با استفاده از firebase deploy )، تابع شما از طریق URL های زیر قابل دسترسی است:

  • زیر دامنه های Firebase شما:
    PROJECT_ID .web.app/bigben و PROJECT_ID .firebaseapp.com/bigben

  • هر دامنه سفارشی متصل:
    CUSTOM_DOMAIN /bigben

هنگام هدایت مجدد درخواست ها به توابع با Hosting ، روش های درخواست HTTP پشتیبانی شده عبارتند از GET ، POST ، HEAD ، PUT ، DELETE ، PATCH و OPTIONS . روش های دیگر مانند REPORT یا PROFIND پشتیبانی نمی شوند.

درخواست‌ها را به یک کانتینر Cloud Run مستقیم کنید

می‌توانید rewrites برای دسترسی به محفظه Cloud Run از URL Firebase Hosting استفاده کنید. مثال زیر گزیده ای از ارائه محتوای پویا با استفاده از Cloud Run است.

به عنوان مثال، برای هدایت همه درخواست‌ها از صفحه /helloworld در سایت Hosting خود برای راه‌اندازی و اجرای یک نمونه کانتینر helloworld :

"hosting": {
 // ...

 // Directs all requests from the page `/helloworld` to trigger and run a `helloworld` container
 "rewrites": [ {
   "source": "/helloworld",
   "run": {
     "serviceId": "helloworld",  // "service name" (from when you deployed the container image)
     "region": "us-central1"  // optional (if omitted, default is us-central1)
   }
 } ]
}

پس از افزودن این قانون بازنویسی و استقرار در Firebase (با استفاده از firebase deploy )، تصویر کانتینر شما از طریق URL های زیر قابل دسترسی است:

  • زیر دامنه های Firebase شما:
    PROJECT_ID .web.app/helloworld و PROJECT_ID .firebaseapp.com/helloworld

  • هر دامنه سفارشی متصل:
    CUSTOM_DOMAIN /helloworld

هنگام هدایت مجدد درخواست ها به کانتینرهای Cloud Run با Hosting ، روش های درخواست HTTP پشتیبانی شده عبارتند از GET ، POST ، HEAD ، PUT ، DELETE ، PATCH و OPTIONS . روش های دیگر مانند REPORT یا PROFIND پشتیبانی نمی شوند.

برای بهترین عملکرد، سرویس Cloud Run خود را با Hosting با استفاده از مناطق زیر یکجا قرار دهید:

  • us-west1
  • us-central1
  • us-east1
  • europe-west1
  • asia-east1

بازنویسی در Cloud Run از Hosting در مناطق زیر پشتیبانی می شود:

  • asia-east1
  • asia-east2
  • asia-northeast1
  • asia-northeast2
  • asia-northeast3
  • asia-south1
  • asia-south2
  • asia-southeast1
  • asia-southeast2
  • australia-southeast1
  • australia-southeast2
  • europe-central2
  • europe-north1
  • europe-southwest1
  • europe-west1
  • europe-west12
  • europe-west2
  • europe-west3
  • europe-west4
  • europe-west6
  • europe-west8
  • europe-west9
  • me-central1
  • me-west1
  • northamerica-northeast1
  • northamerica-northeast2
  • southamerica-east1
  • southamerica-west1
  • us-central1
  • us-east1
  • us-east4
  • us-east5
  • us-south1
  • us-west1
  • us-west2
  • us-west3
  • us-west4
  • us-west1
  • us-central1
  • us-east1
  • europe-west1
  • asia-east1

می‌توانید rewrites برای ایجاد Dynamic Links دامنه سفارشی استفاده کنید. برای اطلاعات دقیق در مورد راه اندازی یک دامنه سفارشی برای Dynamic Links از مستندات Dynamic Links دیدن کنید.

  • از دامنه سفارشی خود فقط برای Dynamic Links استفاده کنید

    "hosting": {
      // ...
    
      "appAssociation": "AUTO",  // required for Dynamic Links (default is AUTO if not specified)
    
      // Add the "rewrites" attribute within "hosting"
      "rewrites": [ {
        "source": "/**",  // the Dynamic Links start with "https://CUSTOM_DOMAIN/"
        "dynamicLinks": true
      } ]
    }
  • پیشوندهای مسیر دامنه سفارشی را برای استفاده برای Dynamic Links مشخص کنید

    "hosting": {
      // ...
    
      "appAssociation": "AUTO",  // required for Dynamic Links (default is AUTO if not specified)
    
      // Add the "rewrites" attribute within "hosting"
      "rewrites": [ {
        "source": "/promos/**",  // the Dynamic Links start with "https://CUSTOM_DOMAIN/promos/"
        "dynamicLinks": true
      }, {
        "source": "/links/share/**",  // the Dynamic Links start with "https://CUSTOM_DOMAIN/links/share/"
        "dynamicLinks": true
      } ]
    }

پیکربندی Dynamic Links در فایل firebase.json به موارد زیر نیاز دارد:

میدان توضیحات
appAssociation

باید روی AUTO تنظیم شود

  • اگر این ویژگی را در پیکربندی خود وارد نکنید، پیش‌فرض برای appAssociation AUTO است.
  • با تنظیم این ویژگی روی AUTO ، Hosting می‌تواند به صورت پویا فایل‌های assetlinks.json و apple-app-site-association را در صورت درخواست ایجاد کند.
rewrites
source

مسیری که می خواهید برای Dynamic Links استفاده کنید

برخلاف قوانینی که مسیرهای URL را بازنویسی می‌کنند، قوانین بازنویسی برای Dynamic Links نمی‌توانند شامل عبارات منظم باشند.

dynamicLinks باید روی true تنظیم شود

هدرها را پیکربندی کنید

اختیاری
هدرها به مشتری و سرور اجازه می دهند اطلاعات اضافی را همراه با درخواست یا پاسخ ارسال کنند. برخی از مجموعه‌های هدر می‌توانند بر نحوه مدیریت مرورگر صفحه و محتوای آن، از جمله کنترل دسترسی، احراز هویت، حافظه پنهان و رمزگذاری تأثیر بگذارند.

با ایجاد یک ویژگی headers که حاوی آرایه ای از اشیاء هدر است، سرصفحه های پاسخ سفارشی و خاص فایل را مشخص کنید. در هر شی، یک الگوی URL را مشخص کنید که اگر با مسیر URL درخواست مطابقت داشته باشد، Hosting برای اعمال هدرهای پاسخ سفارشی مشخص شده فعال می کند.

در اینجا ساختار اصلی برای ویژگی headers آمده است. این مثال هدر CORS را برای همه فایل های فونت اعمال می کند.

"hosting": {
  // ...

  // Applies a CORS header for all font files
  "headers": [ {
    "source": "**/*.@(eot|otf|ttf|ttc|woff|font.css)",
    "headers": [ {
      "key": "Access-Control-Allow-Origin",
      "value": "*"
    } ]
  } ]
}

ویژگی headers شامل آرایه ای از تعاریف است که در آن هر تعریف باید فیلدهای جدول زیر را شامل شود.

میدان توضیحات
headers
source (توصیه می شود)
یا regex

یک الگوی URL که اگر با URL درخواست اولیه مطابقت داشته باشد، Hosting برای اعمال هدر سفارشی فعال می کند

  • از source برای تعیین یک glob استفاده کنید (توصیه می شود) .
  • از regex برای تعیین یک عبارت منظم RE2 استفاده کنید.

برای ایجاد هدر متناسب با صفحه سفارشی 404 خود، از 404.html به عنوان source یا مقدار regex خود استفاده کنید.

آرایه ای از headers (زیر)

هدرهای سفارشی که Hosting در مسیر درخواست اعمال می کند

هر عنوان فرعی باید شامل یک جفت key و value باشد (به دو ردیف بعدی مراجعه کنید).

key نام هدر، برای مثال Cache-Control
value مقدار هدر، برای مثال max-age=7200

می‌توانید در مورد Cache-Control در بخش Hosting که ارائه محتوای پویا و میکروسرویس‌های میزبانی را توضیح می‌دهد، اطلاعات بیشتری کسب کنید. همچنین می‌توانید درباره سرصفحه‌های CORS اطلاعات بیشتری کسب کنید.

پسوندهای .html کنترل کنید

اختیاری
ویژگی cleanUrls به شما امکان می دهد کنترل کنید که آیا URL ها باید شامل پسوند .html باشند یا نه.

هنگامی که true ، Hosting به طور خودکار پسوند .html را از URL های فایل آپلود شده حذف می کند. اگر یک پسوند .html به درخواست اضافه شود، Hosting یک تغییر مسیر 301 به همان مسیر انجام می دهد اما پسوند .html را حذف می کند.

در اینجا نحوه کنترل گنجاندن .html در URL ها با گنجاندن ویژگی cleanUrls آورده شده است:

"hosting": {
  // ...

  // Drops `.html` from uploaded URLs
  "cleanUrls": true
}

اسلش های انتهایی را کنترل کنید

اختیاری
ویژگی trailingSlash به شما امکان می دهد کنترل کنید که آیا URL های محتوای ثابت باید دارای اسلش های انتهایی باشند یا خیر.

  • وقتی true ، Hosting URL ها را برای اضافه کردن یک اسلش دنباله هدایت می کند.
  • وقتی false ، Hosting URL ها را برای حذف یک اسلش دنباله هدایت می کند.
  • وقتی نامشخص باشد، Hosting فقط از اسلش های انتهایی برای فایل های فهرست دایرکتوری استفاده می کند (مثلا about/index.html ).

در اینجا نحوه کنترل اسلش های انتهایی با افزودن ویژگی trailingSlash آورده شده است:

"hosting": {
  // ...

  // Removes trailing slashes from URLs
  "trailingSlash": false
}

ویژگی trailingSlash بر بازنویسی محتوای پویا که توسط Cloud Functions یا Cloud Run ارائه می‌شود، تأثیری ندارد.

تطبیق الگوی گلوب

گزینه‌های پیکربندی Firebase Hosting از نماد تطبیق الگوی glob با extglob استفاده گسترده‌ای می‌کنند، مشابه نحوه مدیریت Git با قوانین gitignore و Bower که قوانین ignore می‌شود. این صفحه ویکی مرجع دقیق تری است، اما در زیر توضیحاتی درباره نمونه های استفاده شده در این صفحه آورده شده است:

  • firebase.json - فقط با فایل firebase.json در ریشه دایرکتوری public مطابقت دارد

  • ** - با هر فایل یا پوشه ای در یک زیر شاخه دلخواه مطابقت دارد

  • * - فقط فایل ها و پوشه های موجود در ریشه دایرکتوری public را منطبق می کند

  • **/.* - با هر فایلی که با . (معمولاً فایل های پنهان، مانند پوشه .git ) در یک زیر شاخه دلخواه

  • **/node_modules/** - با هر فایل یا پوشه ای در یک زیرشاخه دلخواه یک پوشه node_modules مطابقت دارد، که خود می تواند در یک زیر شاخه دلخواه دایرکتوری public باشد.

  • **/*.@(jpg|jpeg|gif|png) - با هر فایلی در یک زیرشاخه دلخواه که دقیقاً با یکی از موارد زیر ختم می شود مطابقت دارد: .jpg ، .jpeg ، .gif ، یا .png

نمونه تنظیمات Hosting کامل

در زیر یک مثال کامل از پیکربندی firebase.json برای Firebase Hosting آورده شده است. توجه داشته باشید که یک فایل firebase.json می‌تواند شامل پیکربندی‌هایی برای سایر سرویس‌های Firebase نیز باشد.

{
  "hosting": {

    "public": "dist/app",  // "public" is the only required attribute for Hosting

    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],

    "redirects": [ {
      "source": "/foo",
      "destination": "/bar",
      "type": 301
    }, {
      "source": "/firebase/**",
      "destination": "https://www.firebase.com",
      "type": 302
    } ],

    "rewrites": [ {
      // Shows the same content for multiple URLs
      "source": "/app/**",
      "destination": "/app/index.html"
    }, {
      // Configures a custom domain for Dynamic Links
      "source": "/promos/**",
      "dynamicLinks": true
    }, {
      // Directs a request to Cloud Functions
      "source": "/bigben",
      "function": "bigben"
    }, {
      // Directs a request to a Cloud Run containerized app
      "source": "/helloworld",
      "run": {
        "serviceId": "helloworld",
        "region": "us-central1"
      }
    } ],

    "headers": [ {
      "source": "**/*.@(eot|otf|ttf|ttc|woff|font.css)",
      "headers": [ {
        "key": "Access-Control-Allow-Origin",
        "value": "*"
      } ]
    }, {
      "source": "**/*.@(jpg|jpeg|gif|png)",
      "headers": [ {
        "key": "Cache-Control",
        "value": "max-age=7200"
      } ]
    }, {
      "source": "404.html",
      "headers": [ {
        "key": "Cache-Control",
        "value": "max-age=300"
      } ]
    } ],

    "cleanUrls": true,

    "trailingSlash": false,

    // Required to configure custom domains for Dynamic Links
    "appAssociation": "AUTO",

  }
}