Định cấu hình hoạt động lưu trữ

Với tính năng Lưu trữ Firebase, bạn có thể định cấu hình hành vi lưu trữ tùy chỉnh cho các yêu cầu đến trang web của mình.

Bạn có thể định cấu hình cài đặt nào cho Dịch vụ lưu trữ?

  • Chỉ định các tệp trong thư mục dự án cục bộ mà bạn muốn triển khai cho tính năng Lưu trữ Firebase. Tìm hiểu cách làm.

  • Phân phát trang 404/Không tìm thấy tuỳ chỉnh. Tìm hiểu cách làm.

  • Thiết lập redirects cho các trang mà bạn đã di chuyển hoặc xoá. Tìm hiểu cách làm.

  • Thiết lập rewrites cho bất kỳ mục đích nào sau đây:

  • Thêm headers để chuyển thông tin bổ sung về một yêu cầu hoặc phản hồi, chẳng hạn như cách trình duyệt sẽ xử lý trang và nội dung của trang (xác thực, lưu vào bộ nhớ đệm, mã hoá, v.v.). Tìm hiểu cách làm.

  • Thiết lập các quy tắc ghi lại quốc tế hoá (i18n) để phân phát nội dung cụ thể dựa trên ngôn ngữ ưu tiên và/hoặc quốc gia của người dùng. Tìm hiểu cách thực hiện (trang khác).

Bạn xác định cấu hình Lưu trữ của mình ở đâu?

Bạn xác định cấu hình Lưu trữ Firebase trong tệp firebase.json. Firebase sẽ tự động tạo tệp firebase.json của bạn ở gốc của thư mục dự án khi bạn chạy lệnh firebase init.

Bạn có thể xem ví dụ đầy đủ về cấu hình firebase.json (chỉ bao gồm tính năng Lưu trữ Firebase) ở cuối trang này. Xin lưu ý rằng tệp firebase.json cũng có thể chứa cấu hình cho các dịch vụ Firebase khác.

Bạn có thể kiểm tra nội dung firebase.json đã triển khai bằng cách sử dụng API REST máy chủ lưu trữ.

Thứ tự ưu tiên của phản hồi Lưu trữ

Các lựa chọn cấu hình Lưu trữ Firebase khác nhau được mô tả trên trang này đôi khi có thể trùng lặp. Nếu có xung đột, tính năng Lưu trữ sẽ xác định phản hồi bằng cách sử dụng thứ tự ưu tiên sau:

  1. Không gian tên dành riêng bắt đầu bằng một phân đoạn đường dẫn /__/*
  2. Lệnh chuyển hướng đã định cấu hình
  3. Nội dung tĩnh khớp chính xác
  4. Ghi lại đã định cấu hình
  5. Trang 404 tuỳ chỉnh
  6. Trang 404 mặc định

Nếu bạn đang sử dụng tính năng ghi lại i18n, thì thứ tự ưu tiên xử lý lỗi i18n và khớp chính xác sẽ được mở rộng trong phạm vi để phù hợp với "nội dung i18n" của bạn.

Chỉ định tệp nào cần triển khai

Các thuộc tính mặc định — publicignore — có trong tệp firebase.json mặc định xác định tệp nào trong thư mục dự án sẽ được triển khai cho dự án Firebase của bạn.

Cấu hình hosting mặc định trong tệp firebase.json sẽ có dạng như sau:

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

công khai

Bắt buộc
Thuộc tính public chỉ định thư mục cần triển khai cho tính năng Lưu trữ Firebase. Giá trị mặc định là một thư mục có tên public, nhưng bạn có thể chỉ định đường dẫn của bất kỳ thư mục nào, miễn là đường dẫn đó tồn tại trong thư mục dự án của bạn.

Sau đây là tên được chỉ định mặc định của thư mục cần triển khai:

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

  // ...
}

Bạn có thể thay đổi giá trị mặc định cho thư mục mà bạn muốn triển khai:

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

  // ...
}

bỏ qua

Không bắt buộc
Thuộc tính ignore chỉ định các tệp cần bỏ qua khi triển khai. Có thể lấy toàn cầu giống như Git xử lý .gitignore.

Sau đây là giá trị mặc định cho các tệp cần bỏ qua:

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

Tuỳ chỉnh trang 404/Không tìm thấy

Không bắt buộc
Bạn có thể phân phát lỗi 404 Not Found tuỳ chỉnh khi người dùng cố gắng truy cập vào một trang không tồn tại.

Tạo một tệp mới trong thư mục public của dự án, đặt tên tệp là 404.html, sau đó thêm nội dung 404 Not Found tuỳ chỉnh vào tệp đó.

Tính năng Lưu trữ Firebase sẽ hiển thị nội dung của trang 404.html tuỳ chỉnh này nếu trình duyệt kích hoạt lỗi 404 Not Found trên miền hoặc miền con của bạn.

Định cấu hình lệnh chuyển hướng

Không bắt buộc
Sử dụng lệnh chuyển hướng URL để ngăn các đường liên kết bị hỏng nếu bạn đã di chuyển một trang hoặc để rút ngắn URL. Ví dụ: bạn có thể chuyển hướng một trình duyệt từ example.com/team đến example.com/about.html.

Chỉ định các lệnh chuyển hướng URL bằng cách tạo thuộc tính redirects chứa một loạt đối tượng (được gọi là "quy tắc chuyển hướng"). Trong mỗi quy tắc, hãy chỉ định một mẫu URL mà nếu khớp với đường dẫn URL yêu cầu, sẽ kích hoạt Lưu trữ để phản hồi bằng lệnh chuyển hướng đến URL đích đã chỉ định.

Đây là cấu trúc cơ bản của thuộc tính redirects. Ví dụ này chuyển hướng các yêu cầu đến /foo bằng cách tạo một yêu cầu mới đến /bar.

"hosting": {
  // ...

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

Thuộc tính redirects chứa một mảng các quy tắc chuyển hướng, trong đó mỗi quy tắc phải bao gồm các trường trong bảng bên dưới.

Tính năng Lưu trữ Firebase so sánh giá trị source hoặc regex với tất cả đường dẫn URL ở đầu mỗi yêu cầu (trước khi trình duyệt xác định liệu tệp hoặc thư mục có tồn tại ở đường dẫn đó hay không). Nếu tìm thấy kết quả trùng khớp, máy chủ gốc Lưu trữ Firebase sẽ gửi phản hồi chuyển hướng HTTPS để yêu cầu trình duyệt gửi một yêu cầu mới tại URL destination.

Trường Mô tả
redirects
source (nên dùng)
hoặc regex

Mẫu URL mà nếu khớp với URL yêu cầu ban đầu sẽ kích hoạt Lưu trữ để áp dụng lệnh chuyển hướng

destination

Một URL tĩnh mà trình duyệt sẽ thực hiện yêu cầu mới

URL này có thể là đường dẫn tương đối hoặc tuyệt đối.

type

Mã phản hồi HTTPS

  • Sử dụng một loại 301 cho "Đã di chuyển vĩnh viễn"
  • Sử dụng một loại 302 cho "Đã tìm thấy" (Chuyển hướng tạm thời)

Ghi lại các phân đoạn URL để chuyển hướng

Không bắt buộc
Đôi khi, bạn có thể cần chụp các phân đoạn cụ thể trong mẫu URL của quy tắc chuyển hướng (giá trị source hoặc regex), sau đó sử dụng lại các phân đoạn này trong đường dẫn destination của quy tắc đó.

Định cấu hình tính năng ghi lại

Không bắt buộc
Sử dụng lệnh viết lại để cho thấy cùng một nội dung cho nhiều URL. Việc viết lại đặc biệt hữu ích trong việc so khớp mẫu, vì bạn có thể chấp nhận bất kỳ URL nào khớp với mẫu và để mã phía máy khách quyết định nội dung sẽ hiển thị.

Bạn cũng có thể sử dụng các lệnh ghi lại để hỗ trợ các ứng dụng sử dụng HTML5 pushState để điều hướng. Khi trình duyệt cố gắng mở một đường dẫn URL khớp với mẫu URL source hoặc regex đã chỉ định, trình duyệt sẽ được cung cấp nội dung của tệp tại URL destination.

Chỉ định việc ghi lại URL bằng cách tạo thuộc tính rewrites chứa một loạt các đối tượng (được gọi là "quy tắc ghi lại"). Trong mỗi quy tắc, hãy chỉ định một mẫu URL mà nếu khớp với đường dẫn URL yêu cầu, sẽ kích hoạt Lưu trữ để phản hồi như thể dịch vụ được cung cấp URL đích đã chỉ định.

Đây là cấu trúc cơ bản của thuộc tính rewrites. Ví dụ này phân phát index.html cho các yêu cầu đến tệp hoặc thư mục không tồn tại.

"hosting": {
  // ...

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

Thuộc tính rewrites chứa một mảng các quy tắc ghi lại, trong đó mỗi quy tắc phải bao gồm các trường trong bảng bên dưới.

Tính năng Lưu trữ Firebase chỉ áp dụng quy tắc ghi lại nếu tệp hoặc thư mục không tồn tại ở đường dẫn URL khớp với mẫu URL source hoặc regex đã chỉ định. Khi một yêu cầu kích hoạt quy tắc ghi lại, trình duyệt sẽ trả về nội dung thực tế của tệp destination được chỉ định thay vì chuyển hướng HTTP.

Trường Mô tả
rewrites
source (nên dùng)
hoặc regex

Mẫu URL mà nếu khớp với URL yêu cầu ban đầu sẽ kích hoạt Lưu trữ để áp dụng lệnh ghi lại

destination

Phải có một tệp cục bộ

URL này có thể là đường dẫn tương đối hoặc tuyệt đối.

Gửi yêu cầu trực tiếp đến một hàm

Bạn có thể sử dụng rewrites để phân phát hàm từ URL lưu trữ Firebase. Ví dụ sau đây là phần trích dẫn từ việc phân phát nội dung động bằng Hàm đám mây.

Ví dụ: để chuyển hướng tất cả các yêu cầu từ trang /bigben trên trang web Lưu trữ của bạn nhằm thực thi hàm 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)
    }
  } ]
}

Sau khi thêm quy tắc ghi lại này và triển khai vào Firebase (sử dụng firebase deploy), bạn có thể truy cập hàm của mình qua các URL sau:

  • Các miền con Firebase của bạn:
    PROJECT_ID.web.app/bigbenPROJECT_ID.firebaseapp.com/bigben

  • Mọi miền tuỳ chỉnh được kết nối:
    CUSTOM_DOMAIN/bigben

Khi chuyển hướng yêu cầu đến các hàm có tính năng Lưu trữ, các phương thức yêu cầu HTTP được hỗ trợ là GET, POST, HEAD, PUT, DELETE, PATCHOPTIONS. Các phương thức khác như REPORT hoặc PROFIND không được hỗ trợ.

Gửi yêu cầu trực tiếp đến một vùng chứa trên Cloud Run

Bạn có thể sử dụng rewrites để truy cập vào vùng chứa Cloud Run từ URL của máy chủ Firebase. Ví dụ sau đây là phần trích dẫn từ nội dung phân phát nội dung động bằng Cloud Run.

Ví dụ: để chuyển hướng tất cả các yêu cầu từ trang /helloworld trên trang web Lưu trữ của bạn nhằm kích hoạt quá trình khởi động và chạy một thực thể vùng chứa 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)
   }
 } ]
}

Sau khi thêm quy tắc ghi lại này và triển khai vào Firebase (sử dụng firebase deploy), hình ảnh vùng chứa của bạn có thể truy cập được qua các URL sau:

  • Các miền con Firebase của bạn:
    PROJECT_ID.web.app/helloworldPROJECT_ID.firebaseapp.com/helloworld

  • Mọi miền tuỳ chỉnh được kết nối:
    CUSTOM_DOMAIN/helloworld

Khi chuyển hướng yêu cầu đến vùng chứa Cloud Run bằng tính năng Lưu trữ, các phương thức yêu cầu HTTP được hỗ trợ là GET, POST, HEAD, PUT, DELETE, PATCHOPTIONS. Các phương thức khác như REPORT hoặc PROFIND không được hỗ trợ.

Để đạt được hiệu suất tốt nhất, hãy bố trí dịch vụ Cloud Run cùng với dịch vụ Lưu trữ thông qua những khu vực sau:

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

Việc ghi lại cho Cloud Run từ máy chủ lưu trữ được hỗ trợ ở các khu vực sau:

  • 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

Bạn có thể sử dụng rewrites để tạo Đường liên kết động cho miền tuỳ chỉnh. Hãy tham khảo tài liệu về Đường liên kết động để biết thông tin chi tiết về cách thiết lập một miền tuỳ chỉnh cho Đường liên kết động.

  • Chỉ sử dụng miền tuỳ chỉnh cho Đường liên kết động

    "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
      } ]
    }
    
  • Chỉ định tiền tố đường dẫn miền tuỳ chỉnh để dùng cho Đường liên kết động

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

Việc định cấu hình đường liên kết động trong tệp firebase.json yêu cầu:

Trường Mô tả
appAssociation

Phải đặt thành AUTO

  • Nếu bạn không đưa thuộc tính này vào cấu hình, thì giá trị mặc định cho appAssociationAUTO.
  • Khi bạn đặt thuộc tính này thành AUTO, dịch vụ Lưu trữ có thể tự động tạo tệp assetlinks.jsonapple-app-site-association khi có yêu cầu.
rewrites
source

Đường dẫn mà bạn muốn sử dụng cho Đường liên kết động

Không giống như các quy tắc ghi lại đường dẫn đến URL, quy tắc viết lại cho Đường liên kết động không được chứa biểu thức chính quy.

dynamicLinks Phải đặt thành true

Định cấu hình tiêu đề

Không bắt buộc
Tiêu đề cho phép máy khách và máy chủ truyền thêm thông tin cùng với yêu cầu hoặc phản hồi. Một số bộ tiêu đề có thể ảnh hưởng đến cách trình duyệt xử lý trang và nội dung của trang, bao gồm kiểm soát quyền truy cập, xác thực, lưu vào bộ nhớ đệm và mã hoá.

Chỉ định các tiêu đề phản hồi tuỳ chỉnh, dành riêng cho tệp bằng cách tạo thuộc tính headers chứa một mảng các đối tượng tiêu đề. Trong mỗi đối tượng, hãy chỉ định một mẫu URL mà nếu khớp với đường dẫn URL yêu cầu, sẽ kích hoạt tính năng Lưu trữ để áp dụng các tiêu đề phản hồi tuỳ chỉnh đã chỉ định.

Đây là cấu trúc cơ bản của thuộc tính headers. Ví dụ này áp dụng tiêu đề ChromeOS cho mọi tệp phông chữ.

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

Thuộc tính headers chứa một mảng các định nghĩa, trong đó mỗi định nghĩa phải bao gồm các trường trong bảng dưới đây.

Trường Mô tả
headers
source (nên dùng)
hoặc regex

Mẫu URL mà nếu khớp với URL yêu cầu ban đầu sẽ kích hoạt Lưu trữ để áp dụng tiêu đề tuỳ chỉnh

Để tạo tiêu đề phù hợp với trang 404 tuỳ chỉnh của bạn, hãy sử dụng 404.html làm giá trị source hoặc regex.

mảng (phụ) headers

Các tiêu đề tuỳ chỉnh mà Lưu trữ áp dụng cho đường dẫn yêu cầu

Mỗi tiêu đề phụ phải bao gồm một cặp keyvalue (xem 2 hàng tiếp theo).

key Tên của tiêu đề, ví dụ: Cache-Control
value Giá trị cho tiêu đề, ví dụ: max-age=7200

Bạn có thể tìm hiểu thêm về Cache-Control trong phần Lưu trữ mô tả việc phân phát nội dung động và lưu trữ các dịch vụ vi mô. Bạn cũng có thể tìm hiểu thêm về tiêu đề CORS.

Kiểm soát tiện ích .html

Không bắt buộc
Thuộc tính cleanUrls cho phép bạn kiểm soát việc các URL có nên chứa phần mở rộng .html hay không.

Khi true, Lưu trữ sẽ tự động bỏ phần mở rộng .html khỏi URL tệp đã tải lên. Nếu tiện ích .html được thêm vào yêu cầu, Lưu trữ sẽ thực hiện chuyển hướng 301 đến cùng một đường dẫn nhưng loại bỏ đuôi .html.

Dưới đây là cách kiểm soát việc đưa .html vào URL bằng cách thêm thuộc tính cleanUrls:

"hosting": {
  // ...

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

Kiểm soát dấu gạch chéo ở cuối

Không bắt buộc
Thuộc tính trailingSlash cho phép bạn kiểm soát việc URL nội dung tĩnh có có dấu gạch chéo ở cuối hay không.

  • Khi true, việc lưu trữ sẽ chuyển hướng các URL để thêm dấu gạch chéo ở cuối.
  • Khi false, việc lưu trữ sẽ chuyển hướng URL để xoá dấu gạch chéo ở cuối.
  • Khi không chỉ định, Lưu trữ chỉ sử dụng dấu gạch chéo ở cuối cho các tệp chỉ mục thư mục (ví dụ: about/index.html).

Dưới đây là cách kiểm soát dấu gạch chéo ở cuối bằng cách thêm thuộc tính trailingSlash:

"hosting": {
  // ...

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

Thuộc tính trailingSlash không ảnh hưởng đến việc ghi lại nội dung động do Cloud Functions hoặc Cloud Run phân phát.

So khớp mẫu hình cầu

Các tuỳ chọn cấu hình Lưu trữ Firebase sử dụng rộng rãi ký hiệu so khớp mẫu toàn cầu với extobb, tương tự như cách Git xử lý các quy tắc gitignoreBower xử lý các quy tắc ignore. Trang wiki này là tài liệu tham khảo chi tiết hơn, nhưng sau đây là giải thích về các ví dụ được sử dụng trên trang này:

  • firebase.json – Chỉ khớp với tệp firebase.json trong thư mục gốc của thư mục public

  • ** – So khớp mọi tệp hoặc thư mục trong một thư mục con tuỳ ý

  • * – Chỉ so khớp các tệp và thư mục trong gốc của thư mục public

  • **/.* – So khớp mọi tệp bắt đầu bằng . (thường là các tệp ẩn, chẳng hạn như trong thư mục .git) trong một thư mục con tuỳ ý

  • **/node_modules/** – So khớp mọi tệp hoặc thư mục trong một thư mục con tuỳ ý của thư mục node_modules (có thể nằm trong một thư mục con tuỳ ý của thư mục public

  • **/*.@(jpg|jpeg|gif|png) – So khớp mọi tệp trong một thư mục con tuỳ ý kết thúc bằng đúng một trong các giá trị sau: .jpg, .jpeg, .gif hoặc .png

Ví dụ về cấu hình Lưu trữ đầy đủ

Sau đây là ví dụ về cấu hình firebase.json đầy đủ cho tính năng Lưu trữ Firebase. Xin lưu ý rằng tệp firebase.json cũng có thể chứa cấu hình cho các dịch vụ Firebase khác.

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

  }
}