Cài đặt, định cấu hình và tích hợp Local Emulator Suite

Bộ trình mô phỏng cục bộ Firebase có thể được cài đặt và định cấu hình cho các môi trường thử nghiệm và nguyên mẫu khác nhau, mọi thứ từ các phiên tạo nguyên mẫu một lần đến quy trình tích hợp liên tục ở quy mô sản xuất.

Cài đặt Bộ giả lập cục bộ

Trước khi cài đặt Emulator Suite, bạn sẽ cần:

  • Node.js phiên bản 16.0 trở lên.
  • Java JDK phiên bản 11 trở lên.

Để cài đặt Bộ giả lập:

  1. Cài đặt Firebase CLI . Nếu bạn chưa cài đặt Firebase CLI, hãy cài đặt ngay bây giờ . Bạn sẽ cần CLI phiên bản 8.14.0 trở lên để sử dụng Bộ giả lập. Bạn có thể kiểm tra phiên bản nào bạn đã cài đặt bằng lệnh sau:
    firebase --version
  2. Nếu bạn chưa làm như vậy, hãy khởi tạo thư mục làm việc hiện tại dưới dạng dự án Firebase, làm theo lời nhắc trên màn hình để chỉ định sản phẩm nào sẽ sử dụng:
    firebase init
  3. Thiết lập Bộ giả lập. Lệnh này bắt đầu trình hướng dẫn cấu hình cho phép bạn chọn trình giả lập quan tâm, tải xuống các tệp nhị phân trình giả lập tương ứng và đặt cổng trình giả lập nếu các giá trị mặc định không phù hợp.
    firebase init emulators

Sau khi trình giả lập được cài đặt, sẽ không có kiểm tra cập nhật nào được thực hiện và sẽ không có tải xuống tự động bổ sung nào cho đến khi bạn cập nhật phiên bản Firebase CLI của mình.

Định cấu hình Bộ giả lập

Bạn có thể tùy ý định cấu hình các cổng mạng của trình giả lập và đường dẫn đến các định nghĩa Quy tắc bảo mật trong tệp firebase.json :

  • Thay đổi cổng trình giả lập bằng cách chạy firebase init emulators hoặc bằng cách chỉnh sửa firebase.json theo cách thủ công.
  • Thay đổi đường dẫn đến các định nghĩa Quy tắc bảo mật bằng cách chỉnh sửa firebase.json theo cách thủ công.

Nếu bạn không định cấu hình các cài đặt này, trình giả lập sẽ lắng nghe trên các cổng mặc định của chúng và Cloud Firestore, Cơ sở dữ liệu thời gian thực và Lưu trữ đám mây cho trình giả lập Firebase sẽ chạy với bảo mật dữ liệu mở.

Yêu cầu Sự miêu tả
trình giả lập khởi tạo Bắt đầu trình hướng dẫn khởi tạo trình giả lập. Xác định trình giả lập sẽ được cài đặt và tùy chọn chỉ định cài đặt cổng trình giả lập. init emulators không phá hủy; chấp nhận mặc định sẽ duy trì cấu hình trình giả lập hiện tại.

cấu hình cổng

Mỗi trình giả lập liên kết với một cổng khác trên máy của bạn với giá trị mặc định ưu tiên.

Giả lập Cổng mặc định
xác thực 9099
Giao diện người dùng bộ giả lập 4000
Chức năng đám mây 5001
sự kiện 9299
Cơ sở dữ liệu thời gian thực 9000
Cửa hàng lửa trên đám mây 8080
Lưu trữ đám mây cho Firebase 9199
Lưu trữ căn cứ hỏa lực 5000
Quán rượu/phụ 8085

Cấu hình ID dự án

Tùy thuộc vào cách bạn gọi trình giả lập, bạn có thể chạy nhiều phiên bản của trình giả lập bằng cách sử dụng các ID dự án Firebase khác nhau hoặc nhiều phiên bản trình mô phỏng cho một ID dự án nhất định. Trong những trường hợp như vậy, các phiên bản trình mô phỏng đang chạy trong một môi trường riêng biệt.

Thông thường, nên đặt một ID dự án cho tất cả các lệnh gọi trình giả lập, để Giao diện người dùng Bộ giả lập, các trình giả lập sản phẩm khác nhau và tất cả các phiên bản đang chạy của một trình giả lập cụ thể có thể giao tiếp chính xác trong mọi trường hợp.

Bộ giả lập cục bộ đưa ra cảnh báo khi phát hiện nhiều ID dự án trong môi trường, tuy nhiên, bạn có thể ghi đè hành vi này bằng cách đặt khóa singleProjectMode thành false trong firebase.json của mình.

Bạn có thể kiểm tra (các) khai báo ID dự án để tìm sự không khớp trong:

  • Dự án mặc định trong dòng lệnh. Theo mặc định, ID dự án sẽ được lấy khi khởi động từ dự án đã chọn với firebase init hoặc firebase use . Để xem danh sách các dự án (và xem dự án nào được chọn), hãy sử dụng firebase projects:list .
  • Quy tắc kiểm tra đơn vị. ID dự án thường được chỉ định trong các cuộc gọi đến các phương thức thư viện Kiểm tra Đơn vị Quy tắc initializeTestEnvironment hoặc initializeTestApp .
  • Dòng lệnh --project cờ. Chuyển cờ --project Firebase CLI sẽ ghi đè dự án mặc định. Bạn sẽ cần đảm bảo giá trị của cờ khớp với ID dự án trong thử nghiệm đơn vị và khởi tạo ứng dụng.

Ngoài ra, hãy kiểm tra các cấu hình ID dự án dành riêng cho nền tảng mà bạn đã đặt trong khi định cấu hình các nền tảng Apple , Android và dự án web của mình.

Cấu hình quy tắc bảo mật

Trình giả lập sẽ lấy cấu hình Quy tắc bảo mật từ database , firestore và các khóa cấu hình storage trong firebase.json .

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore": {
    "rules": "firestore.rules"
  },
  "storage": {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

Chỉ định các tùy chọn Java

Trình giả lập Cơ sở dữ liệu thời gian thực, trình giả lập Cloud Firestore và một phần của trình giả lập Cloud Storage cho Firebase dựa trên Java, có thể được tùy chỉnh bằng các cờ JVM thông qua biến môi trường JAVA_TOOL_OPTIONS .

Ví dụ: nếu bạn gặp phải các lỗi liên quan đến không gian heap Java, bạn có thể tăng kích thước heap Java tối đa lên 4GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

Có thể chỉ định nhiều cờ trong dấu ngoặc kép được phân tách bằng dấu cách, như JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g" . Các cờ chỉ ảnh hưởng đến các thành phần dựa trên Java của trình giả lập và không ảnh hưởng đến các phần khác của Firebase CLI, chẳng hạn như Giao diện người dùng của Emulator Suite.

Khởi động trình giả lập

Bạn có thể khởi động trình giả lập để chạy cho đến khi kết thúc theo cách thủ công hoặc để chạy trong khoảng thời gian của tập lệnh kiểm tra được chỉ định rồi tự động tắt.

Yêu cầu Sự miêu tả
trình giả lập: bắt đầu Bắt đầu trình giả lập cho các sản phẩm Firebase được định cấu hình trong firebase.json . Các quy trình giả lập sẽ tiếp tục chạy cho đến khi dừng rõ ràng. Gọi emulators:start sẽ tải trình giả lập xuống ~/.cache/firebase/emulators/ nếu chúng chưa được cài đặt.
Lá cờ mô tả
--only Không bắt buộc. Giới hạn trình giả lập nào bắt đầu. Cung cấp danh sách tên trình mô phỏng được phân tách bằng dấu phẩy, chỉ định một hoặc nhiều tên 'auth', 'database', 'firestore', 'functions', 'hosting' hoặc 'pubsub'.
--inspect-functions debug_port Không bắt buộc. Sử dụng với trình mô phỏng Chức năng đám mây để bật tính năng gỡ lỗi điểm ngắt của các chức năng tại cổng đã chỉ định (hoặc cổng mặc định 9229 nếu bỏ qua đối số). Lưu ý rằng khi cờ này được cung cấp, trình giả lập Chức năng đám mây sẽ chuyển sang chế độ thực thi được tuần tự hóa đặc biệt, trong đó các chức năng được thực thi trong một quy trình duy nhất, theo thứ tự tuần tự (FIFO); điều này giúp đơn giản hóa việc gỡ lỗi chức năng, mặc dù hành vi này khác với thực thi song song nhiều chức năng trong đám mây.
--export-on-exit= Không bắt buộc. Sử dụng với trình giả lập Xác thực, Cloud Firestore, Cơ sở dữ liệu thời gian thực hoặc Lưu trữ đám mây cho Firebase. Hướng dẫn (các) trình giả lập xuất dữ liệu sang một thư mục khi xảy ra tắt máy, như được mô tả cho lệnh trình emulators:export . Thư mục xuất có thể được chỉ định bằng cờ này: firebase emulators:start --export-on-exit=./saved-data . Nếu --import được sử dụng, đường dẫn xuất sẽ mặc định giống nhau; ví dụ: firebase emulators:start --import=./data-path --export-on-exit . Cuối cùng, nếu muốn, hãy chuyển các đường dẫn thư mục khác nhau tới cờ --import--export-on-exit .
--import= import_directory Không bắt buộc. Sử dụng với trình giả lập Xác thực, Cloud Firestore, Cơ sở dữ liệu thời gian thực hoặc Lưu trữ đám mây cho Firebase. Nhập dữ liệu đã lưu bằng cách sử dụng tùy chọn khởi động --export-on-exit hoặc lệnh emulators:export sang phiên bản Authentication, Cloud Firestore, Realtime Database hoặc Cloud Storage cho phiên bản giả lập Firebase đang chạy. Mọi dữ liệu hiện có trong bộ nhớ giả lập sẽ bị ghi đè.
trình giả lập: exec scriptpath Chạy tập lệnh tại scriptpath sau khi bắt đầu trình giả lập cho các sản phẩm Firebase được định cấu hình trong firebase.json . Các tiến trình giả lập sẽ tự động dừng khi tập lệnh chạy xong.
Lá cờ mô tả
--only Không bắt buộc. Giới hạn trình giả lập nào bắt đầu. Cung cấp danh sách tên trình giả lập được phân tách bằng dấu phẩy, chỉ định một hoặc nhiều tên 'firestore', 'database', 'functions', 'hosting' hoặc 'pubsub'.
--inspect-functions debug_port Không bắt buộc. Sử dụng với trình mô phỏng Chức năng đám mây để bật tính năng gỡ lỗi điểm ngắt của các chức năng tại cổng đã chỉ định (hoặc cổng mặc định 9229 nếu bỏ qua đối số). Lưu ý rằng khi cờ này được cung cấp, trình giả lập Chức năng đám mây sẽ chuyển sang chế độ thực thi được tuần tự hóa đặc biệt, trong đó các chức năng được thực thi trong một quy trình duy nhất, theo thứ tự tuần tự (FIFO); điều này giúp đơn giản hóa việc gỡ lỗi chức năng, mặc dù hành vi này khác với thực thi song song nhiều chức năng trong đám mây.
--export-on-exit= Không bắt buộc. Sử dụng với trình giả lập Xác thực, Cloud Firestore, Cơ sở dữ liệu thời gian thực hoặc Lưu trữ đám mây cho Firebase. Hướng dẫn (các) trình giả lập xuất dữ liệu sang một thư mục khi xảy ra tắt máy, như được mô tả cho lệnh trình emulators:export . Thư mục xuất có thể được chỉ định bằng cờ này: firebase emulators:start --export-on-exit=./saved-data . Nếu --import được sử dụng, đường dẫn xuất sẽ mặc định giống nhau; ví dụ: firebase emulators:start --import=./data-path --export-on-exit . Cuối cùng, nếu muốn, hãy chuyển các đường dẫn thư mục khác nhau tới cờ --import--export-on-exit .
--import= import_directory Không bắt buộc. Sử dụng với trình giả lập Xác thực, Cloud Firestore, Cơ sở dữ liệu thời gian thực hoặc Lưu trữ đám mây cho Firebase. Nhập dữ liệu đã lưu bằng cách sử dụng tùy chọn khởi động --export-on-exit hoặc lệnh emulators:export sang phiên bản Authentication, Cloud Firestore, Realtime Database hoặc Cloud Storage cho phiên bản giả lập Firebase đang chạy. Mọi dữ liệu hiện có trong bộ nhớ giả lập sẽ bị ghi đè.
--ui Không bắt buộc. Chạy Giao diện người dùng giả lập trong quá trình thực thi.

Phương pháp firebase emulators:exec thường phù hợp hơn cho quy trình công việc tích hợp liên tục.

Xuất và nhập dữ liệu giả lập

Bạn có thể xuất dữ liệu từ Xác thực, Cloud Firestore, Cơ sở dữ liệu thời gian thực và Lưu trữ đám mây cho trình giả lập Firebase để sử dụng làm tập dữ liệu cơ sở chung, có thể chia sẻ. Các bộ dữ liệu này có thể được nhập bằng cách sử dụng cờ --import , như được mô tả ở trên.

trình giả lập: xuất export_directory

Xác thực, Cloud Firestore, Cơ sở dữ liệu thời gian thực hoặc Lưu trữ đám mây cho trình giả lập Firebase . Xuất dữ liệu từ Cloud Firestore, Cơ sở dữ liệu thời gian thực hoặc Lưu trữ đám mây đang chạy cho phiên bản giả lập Firebase. export_directory được chỉ định sẽ được tạo nếu nó chưa tồn tại. Nếu thư mục được chỉ định tồn tại, bạn sẽ được nhắc xác nhận rằng dữ liệu xuất trước đó sẽ được ghi đè. Bạn có thể bỏ qua lời nhắc này bằng cờ --force . Thư mục xuất chứa tệp kê khai dữ liệu firebase-export-metadata.json .

Bạn có thể hướng dẫn trình giả lập tự động xuất dữ liệu khi chúng tắt bằng cờ --export-on-exit được mô tả ở trên.

Tích hợp với hệ thống CI của bạn

Chạy hình ảnh Bộ giả lập được chứa trong bộ chứa

Việc cài đặt và cấu hình Bộ giả lập với các bộ chứa trong thiết lập CI điển hình rất đơn giản.

Có một số vấn đề cần lưu ý:

  • Các tệp JAR được cài đặt và lưu vào bộ nhớ đệm tại ~/.cache/firebase/emulators/ .

    • Bạn có thể muốn thêm đường dẫn này vào cấu hình bộ đệm CI của mình để tránh tải xuống nhiều lần.
  • Nếu bạn không có tệp firebase.json trong kho lưu trữ của mình, bạn phải thêm một đối số dòng lệnh vào lệnh emulators:start hoặc emulators:exec để chỉ định trình giả lập nào sẽ được khởi động. Ví dụ,
    --only functions,firestore .

Tạo mã thông báo xác thực (Chỉ trình giả lập lưu trữ)

Nếu quy trình công việc tích hợp liên tục của bạn dựa vào Lưu trữ Firebase thì bạn sẽ cần phải đăng nhập bằng mã thông báo để chạy firebase emulators:exec . Các trình giả lập khác không yêu cầu đăng nhập.

Để tạo mã thông báo, hãy chạy firebase login:ci trên môi trường cục bộ của bạn; điều này không nên được thực hiện từ một hệ thống CI. Làm theo hướng dẫn để xác thực. Bạn chỉ cần thực hiện bước này một lần cho mỗi dự án, vì mã thông báo sẽ hợp lệ trên các bản dựng. Mã thông báo phải được coi như mật khẩu; đảm bảo rằng nó được giữ bí mật.

Nếu môi trường CI của bạn cho phép bạn chỉ định các biến môi trường có thể được sử dụng trong tập lệnh xây dựng, thì chỉ cần tạo một biến môi trường có tên là FIREBASE_TOKEN , với giá trị là chuỗi mã thông báo truy cập. Firebase CLI sẽ tự động chọn biến môi trường FIREBASE_TOKEN và trình giả lập sẽ khởi động bình thường.

Phương án cuối cùng, bạn chỉ cần đưa mã thông báo vào tập lệnh xây dựng của mình, nhưng hãy đảm bảo rằng các bên không đáng tin cậy không có quyền truy cập. Đối với phương pháp mã hóa cứng này, bạn có thể thêm --token "YOUR_TOKEN_STRING_HERE" vào firebase emulators:exec .

Sử dụng API REST của Trung tâm giả lập

Liệt kê các trình giả lập đang chạy

Để liệt kê các trình giả lập hiện đang chạy, hãy gửi yêu cầu GET đến điểm cuối /emulators của Emulator Hub.

curl localhost:4400/emulators

Kết quả sẽ là một đối tượng JSON liệt kê tất cả các trình giả lập đang chạy và cấu hình máy chủ/cổng của chúng, ví dụ:

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

Kích hoạt / Vô hiệu kích hoạt chức năng nền

Trong một số trường hợp, bạn sẽ cần tạm thời vô hiệu hóa chức năng cục bộ và trình kích hoạt tiện ích mở rộng. Ví dụ: bạn có thể muốn xóa tất cả dữ liệu trong trình giả lập Cloud Firestore mà không kích hoạt bất kỳ chức năng onDelete nào đang chạy trong trình giả lập Chức năng đám mây hoặc Tiện ích mở rộng.

Để tạm thời tắt trình kích hoạt chức năng cục bộ, hãy gửi yêu cầu PUT đến điểm cuối /functions/disableBackgroundTriggers của Emulator Hub.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

Kết quả sẽ là một đối tượng JSON mô tả chi tiết trạng thái hiện tại.

{
  "enabled": false
}

Để bật trình kích hoạt chức năng cục bộ sau khi chúng đã bị tắt, hãy gửi yêu cầu PUT đến điểm cuối /functions/enableBackgroundTriggers của Trung tâm giả lập.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Kết quả sẽ là một đối tượng JSON mô tả chi tiết trạng thái hiện tại.

{
  "enabled": true
}

Tích hợp SDK giả lập

Các bảng trong phần này cho biết trình giả lập nào được hỗ trợ bởi SDK dành cho quản trị viên và ứng dụng khách. Tương lai có nghĩa là hỗ trợ giả lập đã được lên kế hoạch nhưng chưa khả dụng.

Tính khả dụng của SDK ứng dụng khách

Android nền tảng của Apple mạng Giao diện người dùng căn cứ hỏa lực
Android
Giao diện người dùng căn cứ hỏa lực
iOS
Giao diện người dùng căn cứ hỏa lực
mạng
Cơ sở dữ liệu thời gian thực 19.4.0 7.2.0 8.0.0 6.4.0 Tương lai không áp dụng
Cửa hàng lửa trên đám mây 21.6.0 7.2.0 8.0.0 6.4.0 Tương lai không áp dụng
xác thực 20.0.0 7.0.0 8.0.0 7.0.0 Tương lai 4.7.2
Lưu trữ đám mây cho Firebase 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0 không áp dụng
Chức năng đám mây 19.1.0 7.2.0 8.0.0 không áp dụng không áp dụng không áp dụng
lưu trữ không áp dụng không áp dụng không áp dụng không áp dụng không áp dụng không áp dụng
Tiện ích mở rộng không áp dụng không áp dụng không áp dụng không áp dụng không áp dụng không áp dụng

Tính khả dụng của SDK quản trị

Nút Java con trăn Đi
Cơ sở dữ liệu thời gian thực 8.6.0 6.10.0 2.18.0 Tương lai
Cửa hàng lửa trên đám mây 8.0.0 6.10.0 3.0.0 1.0.0
xác thực 9.3.0 7.2.0 5.0.0 4.2.0
Lưu trữ đám mây cho Firebase 9.8.0 Tương lai Tương lai Tương lai
Chức năng đám mây không áp dụng không áp dụng không áp dụng không áp dụng
lưu trữ không áp dụng không áp dụng không áp dụng không áp dụng
Tiện ích mở rộng không áp dụng không áp dụng không áp dụng không áp dụng