Tài liệu tham khảo về Firebase CLI

CLI Firebase (GitHub) cung cấp nhiều công cụ để quản lý, xem và triển khai cho các dự án Firebase.

Trước khi sử dụng CLI Firebase, thiết lập một dự án Firebase.

Thiết lập hoặc cập nhật CLI

Cài đặt Firebase CLI

Bạn có thể cài đặt CLI Firebase bằng một phương thức phù hợp với hệ điều hành, cấp độ kinh nghiệm và/hoặc trường hợp sử dụng của bạn. Bất kể bạn cài đặt bằng cách nào CLI, bạn có quyền truy cập vào cùng chức năng và lệnh firebase.

Windows macOS Linux

Máy tính Windows

Bạn có thể cài đặt giao diện dòng lệnh (CLI) Firebase dành cho Windows bằng một trong các cách sau tùy chọn:

macOS hoặc Linux

Bạn có thể cài đặt CLI Firebase cho macOS hoặc Linux bằng một trong các tuỳ chọn sau:

Đăng nhập và kiểm thử CLI Firebase

Sau khi cài đặt CLI, bạn phải xác thực. Sau đó, bạn có thể xác nhận xác thực bằng cách liệt kê các dự án Firebase của bạn.

1. Đăng nhập vào Firebase bằng Tài khoản Google của bạn bằng cách chạy lệnh sau:

   firebase login

   Lệnh này kết nối máy cục bộ của bạn với Firebase và cấp cho bạn quyền truy cập vào các dự án Firebase của bạn.

2. Kiểm tra để đảm bảo CLI được cài đặt đúng cách và truy cập vào tài khoản của bạn bằng cách liệt kê các dự án Firebase. Chạy lệnh sau:

   firebase projects:list

   Danh sách hiển thị phải giống với danh sách dự án Firebase được liệt kê trong bảng điều khiển Firebase.

Cập nhật lên phiên bản CLI mới nhất

Nhìn chung, bạn nên sử dụng phiên bản CLI Firebase mới nhất.

Cách bạn cập nhật phiên bản CLI tuỳ thuộc vào hệ điều hành và cách bạn cài đặt CLI.

Sử dụng CLI với hệ thống CI

CLI Firebase yêu cầu trình duyệt để hoàn tất quá trình xác thực, nhưng CLI hoàn toàn tương thích với CI và các môi trường không có giao diện người dùng khác.

1. Trên máy có trình duyệt, hãy cài đặt CLI Firebase.

2. Bắt đầu quy trình đăng nhập bằng cách chạy lệnh sau:

   firebase login:ci

3. Truy cập vào URL được cung cấp, sau đó đăng nhập bằng Tài khoản Google.

4. In một mã làm mới. Phiên CLI hiện tại sẽ không bị ảnh hưởng.

5. Lưu trữ mã thông báo đầu ra theo cách an toàn nhưng có thể truy cập được trong hệ thống CI.

6. Hãy dùng mã thông báo này khi chạy các lệnh firebase. Bạn có thể sử dụng một trong hai tuỳ chọn sau:

   • Cách 1: Lưu trữ mã thông báo dưới dạng biến môi trường FIREBASE_TOKEN. Hệ thống của bạn sẽ tự động sử dụng mã thông báo này.

   • Cách 2: Chạy tất cả các lệnh firebase bằng Cờ --token TOKEN trong hệ thống CI của bạn.
     Đây là thứ tự ưu tiên để tải mã thông báo: cờ, môi trường dự án Firebase mong muốn.

Khởi chạy dự án Firebase

Nhiều tác vụ phổ biến được thực hiện bằng CLI, chẳng hạn như triển khai cho Firebase dự án, cần có thư mục dự án. Bạn thiết lập một thư mục dự án bằng lệnh firebase init. Thư mục dự án thường giống nhau làm thư mục gốc điều khiển nguồn và sau khi chạy firebase init, Thư mục này chứa cấu hình firebase.json tệp.

Để khởi chạy một dự án Firebase mới, hãy chạy lệnh sau từ bên trong thư mục của ứng dụng:

firebase init

Lệnh firebase init sẽ hướng dẫn bạn thiết lập thư mục dự án và một số sản phẩm Firebase. Trong quá trình khởi chạy dự án, CLI Firebase yêu cầu bạn hoàn thành những việc sau:

• Chọn các sản phẩm Firebase mà bạn muốn thiết lập trong dự án Firebase.

  Bước này sẽ nhắc bạn thiết lập cấu hình cho các tệp cụ thể cho các sản phẩm đã chọn. Để biết thêm chi tiết về những cấu hình này, hãy tham khảo tài liệu của sản phẩm cụ thể (ví dụ: Hosting). Xin lưu ý rằng bạn luôn có thể chạy firebase init sau để thiết lập các sản phẩm Firebase khác.

• Chọn một dự án Firebase mặc định.

  Bước này liên kết thư mục dự án hiện tại với một dự án Firebase để các lệnh dành riêng cho dự án (chẳng hạn như firebase deploy) chạy trên dự án Firebase thích hợp.

  Bạn cũng có thể liên kết nhiều dự án Firebase (chẳng hạn như dự án thử nghiệm và dự án sản xuất) có cùng một dự án thư mục.

Khi kết thúc quá trình khởi chạy, Firebase sẽ tự động tạo 2 tệp sau tại thư mục gốc của thư mục ứng dụng cục bộ:

• Tệp cấu hình firebase.json liệt kê cấu hình dự án của bạn.

• Tệp .firebaserc lưu trữ dự án của bạn ALIAS.

Tệp firebase.json

Lệnh firebase init sẽ tạo một firebase.json trong gốc của thư mục dự án.

Bạn cần có tệp firebase.json để triển khai thành phần bằng CLI Firebase vì tệp này chỉ định những tệp và chế độ cài đặt nào trong thư mục dự án được triển khai cho dự án Firebase. Vì một số chế độ cài đặt có thể được xác định trong dự án của bạn hoặc bảng điều khiển của Firebase, hãy đảm bảo rằng bạn giải quyết mọi xung đột triển khai.

Bạn có thể thiết lập hầu hết các tuỳ chọn Firebase Hosting ngay trong tệp firebase.json. Tuy nhiên, đối với các dịch vụ Firebase khác có thể được triển khai bằng CLI Firebase, lệnh firebase init sẽ tạo các tệp cụ thể để bạn có thể xác định chế độ cài đặt cho các dịch vụ đó, chẳng hạn như tệp index.js cho Cloud Functions. Bạn cũng có thể thiết lập các trình bổ trợ triển khai trước hoặc sau khi triển khai trong tệp firebase.json.

Sau đây là tệp firebase.json mẫu có chế độ cài đặt mặc định nếu bạn chọn Firebase Hosting, Cloud Firestore và Cloud Functions for Firebase (với các tuỳ chọn nguồn TypeScript và tìm lỗi mã nguồn được chọn) trong quá trình khởi chạy.

{
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ]
  },
  "firestore": {
      "rules": "firestore.rules",
      "indexes": "firestore.indexes.json"
  },
  "functions": {
    "predeploy": [
      "npm --prefix \"$RESOURCE_DIR\" run lint",
      "npm --prefix \"$RESOURCE_DIR\" run build"
    ]
  }
}

Mặc dù firebase.json được sử dụng theo mặc định, nhưng bạn có thể truyền cờ --config PATH để chỉ định một tệp cấu hình thay thế.

Cấu hình cho nhiều cơ sở dữ liệu Cloud Firestore

Khi bạn chạy firebase init, tệp firebase.json sẽ chứa một khoá firestore duy nhất tương ứng với cơ sở dữ liệu mặc định của dự án, như minh hoạ ở trên.

Nếu dự án của bạn chứa nhiều cơ sở dữ liệu Cloud Firestore, hãy chỉnh sửa tệp firebase.json để liên kết các tệp nguồn chỉ mục cơ sở dữ liệu và Cloud Firestore Security Rules khác nhau với từng cơ sở dữ liệu. Sửa đổi tệp bằng một mảng JSON, trong đó mỗi cơ sở dữ liệu có một mục.

      "firestore": [
        {
          "database": "(default)",
          "rules": "firestore.default.rules",
          "indexes": "firestore.default.indexes.json"
        },
        {
          "database": "ecommerce",
          "rules": "firestore.ecommerce.rules",
          "indexes": "firestore.ecommerce.indexes.json"
        }
      ],

Các tệp Cloud Functions cần bỏ qua khi triển khai

Tại thời điểm triển khai hàm, CLI sẽ tự động chỉ định danh sách các tệp trong thư mục functions cần bỏ qua. Chiến dịch này ngăn việc triển khai các tệp không liên quan trên phụ trợ có thể tăng kích thước dữ liệu triển khai.

Danh sách các tệp bị bỏ qua theo mặc định (ở định dạng JSON):

"ignore": [
  ".git",
  ".runtimeconfig.json",
  "firebase-debug.log",
  "firebase-debug.*.log",
  "node_modules"
]

Nếu bạn thêm các giá trị tuỳ chỉnh của riêng mình cho ignore trong firebase.json, hãy nhớ giữ lại (hoặc thêm nếu thiếu) danh sách tệp hiển thị ở trên.

Quản lý bí danh dự án

Bạn có thể liên kết nhiều dự án Firebase với cùng một thư mục dự án. Ví dụ: bạn có thể muốn sử dụng một dự án Firebase để tạo bản dựng và một dự án khác để phát hành công khai. Bằng cách sử dụng nhiều môi trường dự án, bạn có thể xác minh các thay đổi trước khi triển khai vào môi trường sản xuất. Lệnh firebase use cho phép bạn chuyển đổi giữa các bí danh cũng như tạo bí danh mới.

Thêm bí danh dự án

Khi bạn chọn một dự án Firebase trong quá trình khởi chạy dự án, dự án sẽ tự động được gán bí danh là default. Tuy nhiên, để cho phép các lệnh dành riêng cho dự án chạy trên một dự án Firebase khác nhưng vẫn sử dụng cùng một dự án thư mục, hãy chạy lệnh sau từ bên trong thư mục dự án của bạn:

firebase use --add

Lệnh này sẽ nhắc bạn chọn một dự án Firebase khác và chỉ định dự án đó làm bí danh. Các chỉ định bí danh được ghi vào tệp .firebaserc bên trong thư mục dự án.

Sử dụng bí danh dự án

Để sử dụng các bí danh dự án Firebase đã chỉ định, hãy chạy bất kỳ lệnh nào sau đây từ trong thư mục dự án của bạn.

Bạn có thể ghi đè dự án đang được sử dụng làm dự án đang hoạt động bằng cách truyền cờ --project bằng bất kỳ lệnh CLI nào. Ví dụ: Bạn có thể đặt CLI để chạy trên một dự án Firebase mà bạn đã chỉ định bí danh staging. Nếu bạn muốn chạy một lệnh duy nhất dựa trên dự án Firebase bạn đã chỉ định bí danh prod, sau đó bạn có thể chạy, chẳng hạn như firebase deploy --project=prod.

Kiểm soát nguồn và bí danh dự án

Nhìn chung, bạn nên kiểm tra tệp .firebaserc trong phần kiểm soát nguồn để cho phép nhóm của bạn chia sẻ bí danh dự án. Tuy nhiên, đối với các dự án nguồn mở hoặc mẫu khởi động, bạn thường không nên kiểm tra trong tệp .firebaserc.

Nếu có một dự án phát triển chỉ để sử dụng, bạn có thể chuyển cờ --project với mỗi lệnh hoặc lần chạy firebase use PROJECT_ID mà không gán bí danh cho dự án Firebase.

Phân phát và kiểm thử dự án Firebase trên máy

Bạn có thể xem và kiểm thử dự án Firebase trên các URL được lưu trữ cục bộ trước khi triển khai công khai. Nếu chỉ muốn kiểm thử một số tính năng, bạn có thể sử dụng danh sách được phân tách bằng dấu phẩy trong cờ trên lệnh firebase serve.

Chạy lệnh sau từ gốc thư mục dự án cục bộ nếu bạn muốn thực hiện một trong hai nhiệm vụ sau:

• Xem nội dung tĩnh cho ứng dụng được lưu trữ trên Firebase.
• Sử dụng Cloud Functions để tạo nội dung động cho Firebase Hosting và bạn muốn sử dụng các hàm HTTP chính thức (đã triển khai) để mô phỏng Hosting trên một URL cục bộ.

firebase serve --only hosting

Mô phỏng dự án bằng các hàm HTTP cục bộ

Chạy bất kỳ lệnh nào sau đây từ thư mục dự án của bạn để mô phỏng dự án bằng các hàm HTTP cục bộ.

• Để mô phỏng các chức năng HTTP và tính năng lưu trữ nhằm kiểm tra trên URL cục bộ, hãy sử dụng trong các lệnh sau:

  firebase serve

  firebase serve --only functions,hosting // uses a flag

• Để chỉ mô phỏng các hàm HTTP, hãy dùng lệnh sau:

  firebase serve --only functions

Kiểm thử từ các thiết bị cục bộ khác

Theo mặc định, firebase serve chỉ phản hồi các yêu cầu của localhost. Chiến dịch này có nghĩa là bạn có thể truy cập nội dung được lưu trữ từ web trong máy tính của mình mà không phải từ các thiết bị khác trên mạng của bạn. Nếu bạn muốn kiểm thử từ các thiết bị cục bộ khác, hãy sử dụng cờ --host, như sau:

firebase serve --host 0.0.0.0  // accepts requests to any host

Triển khai cho một dự án Firebase

Giao diện dòng lệnh (CLI) Firebase quản lý việc triển khai mã và thành phần cho Firebase của bạn dự án, bao gồm:

• Bản phát hành mới của các trang web Firebase Hosting
• Cloud Functions for Firebase mới, đã cập nhật hoặc hiện có
• Giản đồ và trình kết nối mới hoặc được cập nhật cho Firebase Data Connect
• Quy tắc cho Firebase Realtime Database
• Quy tắc cho Cloud Storage for Firebase
• Quy tắc cho Cloud Firestore
• Chỉ mục cho Cloud Firestore

Để triển khai cho một dự án Firebase, hãy chạy lệnh sau từ dự án của bạn thư mục:

firebase deploy

Bạn có thể tuỳ ý thêm nhận xét vào từng lần triển khai. Bình luận này sẽ xuất hiện cùng với thông tin triển khai khác trên trang Firebase Hosting của dự án. Ví dụ:

firebase deploy -m "Deploying the best new feature ever."

Khi sử dụng lệnh firebase deploy, hãy lưu ý những điều sau:

• Để triển khai tài nguyên từ thư mục dự án, thư mục dự án phải có tệp firebase.json. Tệp này là được tạo tự động cho bạn Lệnh firebase init.

• Theo mặc định, firebase deploy sẽ tạo một bản phát hành cho tất cả tài nguyên có thể triển khai trong thư mục dự án. Để triển khai các dịch vụ hoặc tính năng cụ thể của Firebase, sử dụng tính năng triển khai một phần.

Xung đột triển khai đối với quy tắc bảo mật

Đối với Firebase Realtime Database, Cloud Storage for Firebase và Cloud Firestore, bạn có thể xác định các quy tắc bảo mật trong thư mục dự án cục bộ hoặc trong bảng điều khiển Firebase.

Một cách khác để tránh xung đột khi triển khai là sử dụng tính năng triển khai một phần và chỉ xác định các quy tắc trong bảng điều khiển Firebase.

Hạn mức triển khai

Có thể (mặc dù không chắc) bạn có thể vượt quá hạn mức giới hạn tỷ lệ hoặc số lượng hoạt động triển khai Firebase của bạn. Ví dụ: khi triển khai rất nhiều hàm, bạn có thể nhận được thông báo lỗi HTTP 429 Quota. Để giải quyết những vấn đề này, hãy thử bằng tính năng triển khai một phần.

Khôi phục quá trình triển khai

Bạn có thể quay lại một lượt triển khai Firebase Hosting từ trang Firebase Hosting của dự án bằng cách chọn thao tác Rollback (Huỷ bỏ) cho bản phát hành mong muốn.

Hiện tại, bạn không thể khôi phục bản phát hành quy tắc bảo mật cho Firebase Realtime Database, Cloud Storage for Firebase hoặc Cloud Firestore.

Triển khai các dịch vụ Firebase cụ thể

Nếu chỉ muốn triển khai các dịch vụ hoặc tính năng cụ thể của Firebase, bạn có thể sử dụng danh sách được phân tách bằng dấu phẩy trong một cờ trên lệnh firebase deploy. Ví dụ: lệnh sau đây sẽ triển khai nội dung Firebase Hosting và Cloud Storage quy tắc bảo mật.

firebase deploy --only hosting,storage

Bảng sau đây liệt kê các dịch vụ và tính năng có sẵn để triển khai một phần. Tên trong cờ tương ứng với các khoá trong firebase.json.

Triển khai các hàm cụ thể

Khi triển khai hàm, bạn có thể nhắm mục tiêu đến các chức năng cụ thể. Ví dụ:

firebase deploy --only functions:function1

firebase deploy --only functions:function1,functions:function2

Một cách khác là nhóm các hàm thành các nhóm xuất trong Tệp /functions/index.js. Nhóm hàm cho phép bạn triển khai nhiều bằng một lệnh duy nhất.

Ví dụ: bạn có thể viết các hàm sau để xác định groupA và groupB:

var functions = require('firebase-functions/v1');

exports.groupA = {
  function1: functions.https.onRequest(...),
  function2: functions.database.ref('\path').onWrite(...)
}
exports.groupB = require('./groupB');

Trong ví dụ này, một tệp functions/groupB.js riêng chứa thông tin bổ sung hàm xác định cụ thể các hàm trong groupB. Ví dụ:

var functions = require('firebase-functions/v1');

exports.function3 = functions.storage.object().onChange(...);
exports.function4 = functions.analytics.event('in_app_purchase').onLog(...);

Trong ví dụ này, bạn có thể triển khai tất cả các hàm groupA bằng cách chạy sau đây từ thư mục dự án của bạn:

firebase deploy --only functions:groupA

Hoặc bạn có thể nhắm mục tiêu một hàm cụ thể trong nhóm bằng cách chạy lệnh sau :

firebase deploy --only functions:groupA.function1,groupB.function4

Xoá hàm

Giao diện dòng lệnh (CLI) Firebase hỗ trợ các lệnh và tuỳ chọn sau cho xoá các hàm đã triển khai trước đó:

• Xoá tất cả những hàm khớp với tên được chỉ định ở tất cả khu vực:

  firebase functions:delete FUNCTION-1_NAME

• Xoá một hàm được chỉ định đang chạy trong một vùng không phải mặc định:

  firebase functions:delete FUNCTION-1_NAME --region REGION_NAME

• Xoá nhiều hàm:

  firebase functions:delete FUNCTION-1_NAME FUNCTION-2_NAME

• Xoá một nhóm hàm đã chỉ định:

  firebase functions:delete GROUP_NAME

• Bỏ qua lời nhắc xác nhận:

  firebase functions:delete FUNCTION-1_NAME --force

Thiết lập các tác vụ theo tập lệnh trước và sau khi triển khai

Bạn có thể kết nối tập lệnh shell với lệnh firebase deploy để thực hiện các tác vụ triển khai trước hoặc sau khi triển khai. Ví dụ: tập lệnh triển khai trước có thể chuyển đổi mã TypeScript thành JavaScript và trình bổ trợ triển khai sau có thể thông báo cho quản trị viên về việc triển khai nội dung trang web mới đến Firebase Hosting.

Để thiết lập các trình bổ trợ triển khai trước hoặc sau khi triển khai, hãy thêm tập lệnh bash vào tệp cấu hình firebase.json. Bạn có thể xác định các tập lệnh tóm tắt trực tiếp trong tệp firebase.json, hoặc bạn có thể tham chiếu các tệp trong thư mục dự án của bạn.

Ví dụ: tập lệnh sau đây là biểu thức firebase.json cho một tác vụ sau khi triển khai, tác vụ này sẽ gửi một thông báo Slack sau khi triển khai thành công đến Firebase Hosting.

"hosting": {
  // ...

  "postdeploy": "./messageSlack.sh 'Just deployed to Firebase Hosting'",
  "public": "public"
}

Tệp tập lệnh messageSlack.sh nằm trong thư mục dự án và có dạng như sau:

curl -X POST -H 'Content-type: application/json' --data '{"text":"$1"}'
     \https://SLACK_WEBHOOK_URL

Bạn có thể thiết lập các hook predeploy và postdeploy cho bất kỳ những thành phần mà bạn có thể triển khai. Lưu ý rằng việc chạy firebase deploy điều kiện kích hoạt tất cả các nhiệm vụ triển khai trước và sau triển khai đã xác định trong firebase.json. Để chỉ chạy những tác vụ được liên kết với một Dịch vụ Firebase, hãy sử dụng các lệnh triển khai một phần.

Cả hai móc predeploy và postdeploy đều in ra kết quả chuẩn và lỗi các luồng tập lệnh đến thiết bị đầu cuối. Đối với các trường hợp không thành công, hãy lưu ý những điều sau:

• Nếu một trình bổ trợ triển khai trước không hoàn tất như dự kiến, thì quá trình triển khai sẽ bị huỷ.
• Nếu quá trình triển khai không thành công vì bất kỳ lý do gì, thì các trình bổ trợ sau khi triển khai sẽ không được kích hoạt.

Biến môi trường

Trong các tập lệnh chạy trong trình bổ trợ triển khai trước và sau khi triển khai, bạn có thể sử dụng các biến môi trường sau:

• $GCLOUD_PROJECT: Mã dự án của dự án đang hoạt động
• $PROJECT_DIR: Thư mục gốc chứa tệp firebase.json
• $RESOURCE_DIR: (Chỉ dành cho tập lệnh hosting và functions) Cụm từ vị trí của thư mục chứa Hosting hoặc Cloud Functions tài nguyên sẽ được triển khai

Quản lý nhiều phiên bản Realtime Database

Một dự án Firebase có thể có nhiều thực thể Firebase Realtime Database. Theo theo mặc định, các lệnh CLI sẽ tương tác với thực thể cơ sở dữ liệu mặc định của bạn.

Tuy nhiên, bạn có thể tương tác với một thực thể cơ sở dữ liệu không mặc định bằng cách sử dụng Cờ --instance DATABASE_NAME. Chiến lược phát hành đĩa đơn các lệnh sau có hỗ trợ cờ --instance:

• firebase database:get
• firebase database:profile
• firebase database:push
• firebase database:remove
• firebase database:set
• firebase database:update

Tham chiếu lệnh

Lệnh quản trị CLI

Lệnh quản lý dự án

Triển khai và phát triển cục bộ

Các lệnh này cho phép bạn triển khai và tương tác với trang web Firebase Hosting của mình.

App Distribution lệnh

Lệnh App Hosting

Các lệnh Authentication (quản lý người dùng)

Cloud Firestore lệnh

Cloud Functions for Firebase lệnh

Để biết thêm thông tin, hãy tham khảo môi trường tài liệu về cấu hình.

Crashlytics lệnh

Lệnh Data Connect

Các lệnh này và trường hợp sử dụng của chúng được đề cập chi tiết hơn trong Hướng dẫn tham khảo về CLI Data Connect.

Extensions lệnh

Extensions lệnh của nhà xuất bản

Lệnh Hosting

Realtime Database lệnh

Xin lưu ý rằng bạn có thể tạo phiên bản ban đầu, mặc định của Realtime Database trong bảng điều khiển Firebase hoặc bằng cách sử dụng firebase init chung quy trình công việc hoặc quy trình Quy trình firebase init database.

Sau khi tạo các thực thể, bạn có thể quản lý các thực thể đó như đã thảo luận trong phần Quản lý nhiều thực thể Realtime Database.

Lệnh Remote Config