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

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

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

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

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

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

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

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

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

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

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

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

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

ترتیب اولویت پاسخ های میزبانی

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

  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 مستقر شود. مقدار پیش‌فرض دایرکتوری با نام 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 محتوای این صفحه سفارشی 404.html را نمایش می دهد.

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

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

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

در اینجا ساختار اصلی برای یک ویژگی redirects آمده است. این مثال با ایجاد یک درخواست جدید به / /foo ، درخواست ها را به /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 source یا مقدار regex را با تمام مسیرهای URL در شروع هر درخواست مقایسه می کند (قبل از اینکه مرورگر تعیین کند که آیا یک فایل یا پوشه در آن مسیر وجود دارد یا خیر). اگر مطابقت پیدا شد، سرور اصلی میزبانی Firebase یک پاسخ تغییر مسیر HTTPS را ارسال می‌کند و به مرورگر می‌گوید درخواست جدیدی در URL destination ارسال کند.

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

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

  • از 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 درخواست مطابقت داشته باشد، میزبانی را فعال می‌کند تا به گونه‌ای پاسخ دهد که گویی 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 تنها زمانی قانون بازنویسی را اعمال می‌کند که فایل یا دایرکتوری در مسیر URL وجود نداشته باشد که با source مشخص شده یا الگوی URL regex مطابقت داشته باشد. هنگامی که یک درخواست یک قانون بازنویسی را راه اندازی می کند، مرورگر محتوای واقعی فایل destination مشخص شده را به جای تغییر مسیر HTTP برمی گرداند.

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

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

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

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

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

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

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

به عنوان مثال، برای هدایت همه درخواست ها از صفحه /bigben در سایت میزبانی خود برای اجرای تابع 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

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

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

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

به عنوان مثال، برای هدایت همه درخواست‌ها از صفحه /helloworld در سایت میزبانی خود برای راه‌اندازی و اجرای یک نمونه کانتینر 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 با میزبانی، روش‌های درخواست HTTP پشتیبانی شده عبارتند از GET ، POST ، HEAD ، PUT ، DELETE ، PATCH و OPTIONS . روش های دیگر مانند REPORT یا PROFIND پشتیبانی نمی شوند.

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

  • 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 برای ایجاد پیوندهای پویا دامنه سفارشی استفاده کنید. برای اطلاعات دقیق در مورد راه اندازی یک دامنه سفارشی برای پیوندهای پویا، از مستندات پیوندهای پویا دیدن کنید.

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

    "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
      } ]
    }
    
  • پیشوندهای مسیر دامنه سفارشی را برای استفاده برای پیوندهای پویا مشخص کنید

    "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
      } ]
    }
    

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

رشته شرح
appAssociation

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

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

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

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

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

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

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

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

در اینجا ساختار اصلی برای ویژگی 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 درخواست اولیه مطابقت داشته باشد، میزبانی را برای اعمال هدر سفارشی فعال می کند

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

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

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

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

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

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

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

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

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

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

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

"hosting": {
  // ...

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

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

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

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

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

"hosting": {
  // ...

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

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

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

گزینه‌های پیکربندی میزبانی Firebase از نماد تطبیق الگوی 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 .

نمونه تنظیمات میزبانی کامل

در زیر یک مثال کامل از پیکربندی firebase.json برای میزبانی Firebase آورده شده است. توجه داشته باشید که یک فایل 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",

  }
}