Mengonfigurasi perilaku hosting

Dengan Firebase Hosting, Anda dapat mengonfigurasi perilaku hosting yang disesuaikan untuk permintaan ke situs Anda.

Apa yang dapat Anda konfigurasi untuk Hosting?

• Tentukan file dalam direktori project lokal yang ingin Anda deploy ke Firebase Hosting. Pelajari caranya.

• Menampilkan halaman 404/Tidak Ditemukan yang disesuaikan. Pelajari caranya.

• Menyiapkan redirects untuk halaman yang telah dipindahkan atau dihapus. Pelajari caranya.

• Menyiapkan rewrites untuk tujuan ini:

  • Menampilkan konten yang sama untuk beberapa URL. Pelajari caranya.

  • Menyajikan fungsi atau mengakses container Cloud Run dari URL Hosting. Pelajari caranya: fungsi atau container.

  • Membuat domain kustom Dynamic Link. Pelajari caranya.

• Menambahkan headers untuk meneruskan informasi tambahan tentang permintaan atau respons, seperti cara browser akan menangani halaman dan kontennya (autentikasi, caching, encoding, dll.) Pelajari caranya.

• Menyiapkan penulisan ulang internasionalisasi (i18n) untuk menayangkan konten tertentu berdasarkan preferensi bahasa dan/atau negara pengguna. Pelajari caranya (halaman berbeda).

Di mana Anda menentukan konfigurasi Hosting?

Anda menentukan konfigurasi Firebase Hosting di file firebase.json. Firebase secara otomatis membuat file firebase.json di root direktori project saat Anda menjalankan perintah firebase init.

Anda dapat menemukan contoh konfigurasi firebase.json lengkap (hanya mencakup Firebase Hosting) di bagian bawah halaman ini. Perhatikan bahwa file firebase.json juga dapat berisi konfigurasi untuk layanan Firebase lainnya.

Anda dapat memeriksa konten firebase.json yang di-deploy menggunakan Hosting REST API.

Urutan prioritas respons Hosting

Berbagai opsi konfigurasi Firebase Hosting yang dijelaskan di halaman ini terkadang dapat tumpang tindih. Jika ada konflik, Hosting menentukan responsnya menggunakan urutan prioritas berikut:

1. Namespace yang dicadangkan yang dimulai dengan segmen jalur /__/*
2. Pengalihan yang dikonfigurasi
3. Konten statis yang sama persis
4. Penulisan ulang yang dikonfigurasi
5. Halaman 404 kustom
6. Halaman 404 default

Jika Anda menggunakan penulisan ulang i18n, urutan prioritas penanganan pencocokan persis dan 404 akan diperluas cakupannya untuk mengakomodasi "konten i18n".

Menentukan file yang akan di-deploy

Atribut default — public dan ignore — yang disertakan dalam file firebase.json default menentukan file mana saja di direktori project yang harus di-deploy ke project Firebase.

Konfigurasi hosting default dalam file firebase.json akan terlihat seperti ini:

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

publik

Wajib
Atribut public menentukan direktori yang akan di-deploy ke Firebase Hosting. Nilai default-nya adalah direktori bernama public, tetapi Anda dapat menentukan jalur direktori mana pun selama berada di direktori project Anda.

Berikut adalah nama direktori default yang ditentukan untuk di-deploy:

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

  // ...
}

Anda dapat mengubah nilai default ke direktori yang ingin Anda deploy:

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

  // ...
}

ignore

Opsional
Atribut ignore menentukan file yang akan diabaikan saat di-deploy. Atribut ini bisa menangani glob dengan cara yang sama seperti Git menangani .gitignore.

Berikut ini adalah nilai default untuk file yang akan diabaikan:

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

Menyesuaikan halaman 404/Tidak Ditemukan

Opsional
Anda dapat menayangkan error 404 Not Found kustom saat pengguna mencoba mengakses halaman yang tidak ada.

Buat file baru di direktori public project, beri nama 404.html, lalu tambahkan konten 404 Not Found kustom ke file tersebut.

Firebase Hosting akan menampilkan konten halaman 404.html kustom ini jika browser memicu error 404 Not Found di domain atau subdomain Anda.

Mengonfigurasi pengalihan

Opsional
Gunakan pengalihan URL untuk mencegah munculnya link rusak ketika Anda memindahkan halaman atau perlu mempersingkat URL. Misalnya, Anda dapat mengalihkan browser dari example.com/team ke example.com/about.html.

Tentukan pengalihan URL dengan membuat atribut redirects yang berisi array objek (disebut "aturan pengalihan"). Di setiap aturan, tentukan pola URL yang, jika cocok dengan jalur URL permintaan, akan memicu Hosting untuk merespons dengan pengalihan ke URL tujuan yang ditentukan.

Berikut adalah struktur dasar untuk atribut redirects. Contoh ini mengalihkan permintaan ke /foo dengan membuat permintaan baru ke /bar.

"hosting": {
  // ...

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

"hosting": {
  // ...

  // Add the "redirects" attribute within "hosting"
  "redirects": [ {
    // Returns a permanent redirect to "/bar" for requests to "/foo" (but not "/foo/**")
    "source": "/foo",
    "destination": "/bar",
    "type": 301
  }, {
    // Returns a permanent redirect to "/bar" for requests to both "/foo" and "/foo/**"
    "source": "/foo{,/**}"
    "destination": "/bar"
    "type": 301
  }, {
    // Returns a temporary redirect for all requests to files or directories in the "firebase" directory
    "source": "/firebase/**",
    "destination": "https://firebase.google.com/",
    "type": 302
  }, {
    // A regular expression-based redirect equivalent to the above behavior
    "regex": "/firebase/.*",
    "destination": "https://firebase.google.com/",
    "type": 302
  } ]
}

Atribut redirects berisi array aturan pengalihan. Dalam array tersebut, setiap aturan harus menyertakan kolom pada tabel di bawah.

Firebase Hosting membandingkan nilai source atau regex terhadap semua jalur URL di awal setiap permintaan (sebelum browser menentukan apakah file atau folder ada di jalur tersebut). Jika kecocokan ditemukan, server asal Firebase Hosting akan mengirimkan respons pengalihan HTTPS yang memerintahkan browser untuk membuat permintaan baru di URL destination.

Mengambil segmen URL untuk pengalihan

Opsional
Terkadang, Anda mungkin perlu mengambil segmen tertentu dari pola URL aturan pengalihan (nilai source atau regex), lalu menggunakan kembali segmen ini di jalur destination aturan tersebut.

"hosting": {
  // ...

  "redirects": [ {
    "source": "/blog/:post*",  // captures the entire URL segment beginning at "post"
    "destination": "https://blog.myapp.com/:post", // includes the entire URL segment identified and captured by the "source" value
    "type": 301
  }, {
    "source": "/users/:id/profile",  // captures only the URL segment "id", but nothing following
    "destination": "/users/:id/newProfile",  // includes the URL segment identified and captured by the "source" value
    "type": 301
  } ]
}

"hosting": {
  // ...

  "redirects": [ {
    "regex": "/blog/(?P<post>.+)",  // if you're familiar with PCRE, be aware that RE2 requires named capture groups to begin with ?P
    "destination": "https://blog.myapp.com/:post",  // includes the entire URL segment identified and captured by the `regex` value
    "type": 301
  }, {
    "regex": "/users/(\d+)/profile",  // uses the \d directive to only match numerical path segments
    "destination": "/users/:1/newProfile",  // the first capture group to be seen in the `regex` value is named 1, and so on
    "type": 301
  } ]
}

Mengonfigurasi penulisan ulang

Opsional
Gunakan penulisan ulang guna menampilkan konten yang sama untuk beberapa URL. Penulisan ulang sangat berguna dengan pencocokan pola karena Anda bisa menerima URL apa pun yang cocok dengan pola dan mengizinkan kode sisi klien memutuskan apa yang akan ditampilkan.

Anda juga dapat menggunakan penulisan ulang untuk mendukung aplikasi yang menggunakan pushState HTML5 untuk navigasi. Saat browser mencoba membuka jalur URL yang cocok dengan pola URL source atau regex yang ditentukan, browser tersebut akan diberi konten file di URL destination.

Tentukan penulisan ulang URL dengan membuat atribut rewrites yang berisi array objek (disebut "aturan penulisan ulang"). Di setiap aturan, tentukan pola URL yang, jika cocok dengan jalur URL permintaan, akan memicu Hosting untuk merespons seolah-olah layanan diberi URL tujuan yang ditentukan.

Berikut adalah struktur dasar untuk atribut rewrites. Contoh ini menampilkan index.html untuk permintaan ke file atau direktori yang tidak ada.

"hosting": {
  // ...

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

"hosting": {
// ...

// Add the "rewrites" attribute within "hosting"
"rewrites": [ {
  // Serves index.html for requests to files or directories that do not exist
  "source": "**",
  "destination": "/index.html"
}, {
  // Serves index.html for requests to both "/foo" and "/foo/**"
  // Using "/foo/**" only matches paths like "/foo/xyz", but not "/foo"
  "source": "/foo{,/**}",
  "destination": "/index.html"
}, {
  // A regular expression-based rewrite equivalent to the above behavior
  "regex": "/foo(/.*)?",
  "destination": "/index.html"
}, {
  // Excludes specified pathways from rewrites
  "source": "!/@(js|css)/**",
  "destination": "/index.html"
} ]
}

Atribut rewrites berisi array aturan penulisan ulang. Dalam array tersebut, setiap aturan harus menyertakan kolom pada tabel di bawah.

Firebase Hosting hanya menerapkan aturan penulisan ulang jika file atau direktori tidak ada di jalur URL yang cocok dengan pola URL source atau regex yang ditentukan. Saat permintaan memicu aturan penulisan ulang, browser akan menampilkan konten asli dari file destination yang ditentukan, bukan pengalihan HTTP.

Permintaan langsung ke fungsi

Anda dapat menggunakan rewrites untuk menayangkan fungsi dari URL Firebase Hosting. Contoh berikut adalah kutipan dari penayangan konten dinamis menggunakan Cloud Functions.

Misalnya, untuk mengalihkan semua permintaan dari halaman /bigben di situs Hosting Anda untuk menjalankan fungsi 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)
    }
  } ]
}

Setelah menambahkan aturan penulisan ulang ini dan men-deploy ke Firebase (menggunakan firebase deploy), fungsi Anda dapat dijangkau melalui URL berikut:

• Subdomain Firebase Anda:
  PROJECT_ID.web.app/bigben dan PROJECT_ID.firebaseapp.com/bigben

• Semua domain kustom yang terhubung:
  CUSTOM_DOMAIN/bigben

Saat mengalihkan permintaan ke fungsi dengan Hosting, metode permintaan HTTP yang didukung adalah GET, POST, HEAD, PUT, DELETE, PATCH, dan OPTIONS. Metode lain seperti REPORT atau PROFIND tidak didukung.

Mengarahkan permintaan ke container Cloud Run

Anda dapat menggunakan rewrites untuk mengakses container Cloud Run dari URL Firebase Hosting. Contoh berikut adalah kutipan dari penayangan konten dinamis menggunakan Cloud Run.

Misalnya, untuk mengarahkan semua permintaan dari halaman /helloworld di situs Hosting Anda untuk memicu startup dan menjalankan instance container 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)
   }
 } ]
}

Setelah menambahkan aturan penulisan ulang ini dan men-deploy ke Firebase (menggunakan firebase deploy), image container Anda dapat dijangkau melalui URL berikut:

• Subdomain Firebase Anda:
  PROJECT_ID.web.app/helloworld dan PROJECT_ID.firebaseapp.com/helloworld

• Semua domain kustom yang terhubung:
  CUSTOM_DOMAIN/helloworld

Saat mengalihkan permintaan ke container Cloud Run dengan Hosting, metode permintaan HTTP yang didukung adalah GET, POST, HEAD, PUT, DELETE, PATCH, dan OPTIONS. Metode lain seperti REPORT atau PROFIND tidak didukung.

Untuk performa terbaik, lakukan kolokasi layanan Cloud Run dengan Hosting menggunakan region berikut:

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

Penulisan ulang ke Cloud Run dari Hosting didukung di region berikut:

• 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

Membuat domain kustom Dynamic Links

Anda dapat menggunakan rewrites untuk membuat domain kustom Dynamic Links. Buka dokumentasi Dynamic Links untuk mengetahui informasi mendetail tentang cara menyiapkan domain kustom untuk Dynamic Links.

• Menggunakan domain kustom Anda hanya untuk 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
    } ]
  }

• Menentukan awalan jalur domain kustom yang akan digunakan untuk 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
    } ]
  }

Mengonfigurasi Dynamic Links di file firebase.json Anda memerlukan hal berikut:

Mengonfigurasi header

Opsional
Dengan header, klien dan server dapat meneruskan informasi tambahan bersama dengan permintaan atau respons. Beberapa kumpulan header dapat memengaruhi cara browser menangani halaman dan kontennya, termasuk kontrol akses, autentikasi, caching, dan encoding.

Tentukan header respons kustom dan khusus untuk file dengan membuat atribut headers yang berisi array objek header. Di setiap objek, tentukan pola URL yang, jika cocok dengan jalur URL permintaan, akan memicu Hosting untuk menerapkan header respons kustom yang ditentukan.

Berikut adalah struktur dasar untuk atribut headers. Contoh ini akan menerapkan header CORS untuk semua file font.

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

"hosting": {
  // ...

  // Add the "headers" attribute within "hosting"
  "headers": [ {
    // Applies a CORS header for all font files
    "source": "**/*.@(eot|otf|ttf|ttc|woff|font.css)",
    "headers": [ {
      "key": "Access-Control-Allow-Origin",
      "value": "*"
    } ]
  }, {
    // Overrides the default 1 hour browser cache with a 2 hour cache for all image files
    "source": "**/*.@(jpg|jpeg|gif|png)",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=7200"
    } ]
  }, {
    // A regular expression-based rewrite equivalent to the above behavior
    "regex": ".+/\w+\.(jpg|jpeg|gif|png)$",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=7200"
    } ]
  }, {
    // Sets the cache header for 404 pages to cache for 5 minutes
    "source": "404.html",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=300"
    } ]
  } ]
}

Atribut headers berisi array definisi, tempat setiap definisi harus menyertakan kolom pada tabel di bawah.

Anda dapat mempelajari Cache-Control lebih lanjut di bagian Hosting yang menjelaskan cara menayangkan konten dinamis dan menghosting microservice. Anda juga dapat mempelajari header CORS lebih lanjut.

Mengontrol ekstensi .html

Opsional
Atribut cleanUrls dapat digunakan untuk mengontrol apakah URL harus menyertakan ekstensi .html atau tidak.

Saat true, Hosting menghapus ekstensi .html secara otomatis dari URL file yang diupload. Jika ekstensi .html ditambahkan di permintaan, Hosting melakukan pengalihan 301 ke jalur yang sama tetapi akan menghilangkan ekstensi .html.

Berikut adalah cara mengontrol penyertaan .html di URL dengan menyertakan atribut cleanUrls:

"hosting": {
  // ...

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

Mengontrol garis miring penutup

Opsional
Atribut trailingSlash memungkinkan Anda mengontrol apakah URL konten statis harus menyertakan garis miring penutup di belakangnya atau tidak.

• Saat true, Hosting mengalihkan URL untuk menambahkan garis miring penutup.
• Saat false, Hosting mengalihkan URL untuk menghapus garis miring penutup.
• Jika tidak ditentukan, Hosting hanya akan menggunakan garis miring penutup untuk file indeks direktori (misalnya, about/index.html).

Berikut cara mengontrol garis miring penutup dengan menambahkan atribut trailingSlash:

"hosting": {
  // ...

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

Atribut trailingSlash tidak memengaruhi penulisan ulang ke konten dinamis yang disajikan oleh Cloud Functions atau Cloud Run.

Pencocokan pola glob

Opsi konfigurasi Firebase Hosting sering kali memanfaatkan notasi pencocokan pola glob dengan extglob, mirip dengan cara Git menangani aturan gitignore dan cara Bower menangani aturan ignore. Halaman wiki ini adalah referensi yang lebih detail, tetapi berikut ini adalah penjelasan dari contoh yang digunakan di halaman ini:

• firebase.json — Hanya mencocokkan file firebase.json di root direktori public

• ** — Mencocokkan file atau folder apa pun di sub-direktori arbitrer

• * — Hanya mencocokkan file dan folder di root dari direktori public

• **/.* — Mencocokkan file yang diawali dengan . (biasanya file tersembunyi, seperti di folder.git) di sub-direktori arbitrer

• **/node_modules/** — Mencocokkan file atau folder apa pun di sub-direktori arbitrer dari folder node_modules, yang dengan sendirinya juga bisa berada di dalam sub-direktori arbitrer dari direktori public

• **/*.@(jpg|jpeg|gif|png) — Mencocokkan file apa pun di sub-direktori arbitrer yang diakhiri dengan salah satu ekstensi berikut: .jpg, .jpeg, .gif, atau .png

Contoh konfigurasi Hosting lengkap

Berikut adalah contoh konfigurasi firebase.json lengkap untuk Firebase Hosting. Perhatikan bahwa file firebase.json juga dapat berisi konfigurasi untuk layanan Firebase lainnya.

{
  "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",

  }
}