Cài đặt, định cấu hình và tích hợp Bộ công cụ mô phỏng cục bộ

Bạn có thể cài đặt và định cấu hình Bộ trình mô phỏng cục bộ Firebase cho nhiều môi trường thử nghiệm và nguyên mẫu, 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 trên quy mô sản xuất.

Cài đặt Bộ công cụ mô phỏng trên thiết bị

Trước khi cài đặt Bộ trình mô phỏng, bạn cần:

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

Cách cài đặt Bộ trình mô phỏng:

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

Sau khi cài đặt trình mô phỏng, hệ thống sẽ không kiểm tra bản cập nhật và không tải xuống tự động thêm cho đến khi bạn cập nhật phiên bản Firebase CLI.

Định cấu hình Bộ công cụ mô phỏng

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

  • Thay đổi cổng trình mô phỏng bằng cách chạy firebase init emulators hoặc chỉnh sửa firebase.json theo cách thủ công.
  • Thay đổi đường dẫn đến đị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 chế độ cài đặt này, trình mô phỏng sẽ nghe trên các cổng mặc định và trình mô phỏng Cloud Firestore, Realtime DatabaseCloud Storage for Firebase sẽ chạy với chế độ bảo mật dữ liệu mở.

Lệnh Nội dung mô tả
khởi động trình mô phỏng Khởi động trình hướng dẫn khởi chạy trình mô phỏng. Xác định trình mô phỏng cần cài đặt và tuỳ ý chỉ định chế độ cài đặt cổng trình mô phỏng. init emulators không gây huỷ hoại; việc chấp nhận các giá trị mặc định sẽ giữ nguyên cấu hình trình mô phỏng hiện tại.

Cấu hình cổng

Mỗi trình mô phỏng liên kết với một cổng khác nhau trên máy của bạn bằng một giá trị mặc định ưu tiên.

Trình mô phỏng Cổng mặc định
Authentication 9099
App Hosting 5002
Emulator Suite UI 4000
Cloud Functions 5001
Eventarc 9299
Realtime Database 9000
Cloud Firestore 8080
Cloud Storage for Firebase 9199
Firebase Hosting 5000
Pub/Sub 8085

Cấu hình mã dự án

Tuỳ thuộc vào cách bạn gọi trình mô phỏng, bạn có thể chạy nhiều thực thể của trình mô phỏng bằng nhiều mã dự án Firebase hoặc nhiều thực thể trình mô phỏng cho một mã dự án nhất định. Trong những trường hợp như vậy, các thực thể trình mô phỏng đang chạy trong một môi trường riêng biệt.

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

Local Emulator Suite đưa ra cảnh báo khi phát hiện nhiều mã dự án trong môi trường, mặc dù bạn có thể ghi đè hành vi này bằng cách đặt khoá singleProjectMode thành false trong firebase.json.

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

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

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

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

Trình mô phỏng sẽ lấy cấu hình Quy tắc bảo mật từ các khoá cấu hình database, firestorestorage 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 tuỳ chọn Java

Trình mô phỏng Realtime Database, trình mô phỏng Cloud Firestore và một phần của trình mô phỏng Cloud Storage for Firebase dựa trên Java, có thể được tuỳ chỉnh bằng cờ JVM thông qua biến môi trường JAVA_TOOL_OPTIONS.

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

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

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

Khởi động trình mô phỏng

Bạn có thể bắt đầu trình mô phỏng để chạy cho đến khi bị chấm dứt theo cách thủ công hoặc để chạy trong khoảng thời gian của một tập lệnh kiểm thử được chỉ định, sau đó tự động tắt.

Lệnh Nội dung mô tả
emulators:start Khởi động trình mô phỏng cho các sản phẩm Firebase được định cấu hình trong firebase.json. Các quy trình của trình mô phỏng sẽ tiếp tục chạy cho đến khi bạn dừng một cách rõ ràng. Thao tác gọi emulators:start sẽ tải trình mô phỏng xuống ~/.cache/firebase/emulators/ nếu bạn chưa cài đặt trình mô phỏng.
Cờ Nội dung mô tả
--only Không bắt buộc. Giới hạn số lượng trình mô phỏng 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 trong số "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 Cloud Functions để bật tính năng gỡ lỗi điểm ngắt của các hàm tại cổng được chỉ định (hoặc cổng mặc định 9229 nếu bỏ qua đối số). Xin lưu ý rằng khi bạn cung cấp cờ này, trình mô phỏng Cloud Functions sẽ chuyển sang chế độ thực thi tuần tự đặc biệt, trong đó các hàm đượ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 hoá việc gỡ lỗi hàm, mặc dù hành vi này khác với việc thực thi song song nhiều quy trình của các hàm trên đám mây.
--export-on-exit= Không bắt buộc. Sử dụng với trình mô phỏng Authentication, Cloud Firestore, Realtime Database hoặc Cloud Storage for Firebase. Hướng dẫn(các) trình mô phỏng xuất dữ liệu sang một thư mục khi quá trình tắt xảy ra, như mô tả cho lệnh emulators:export. Bạn có thể chỉ định thư mục xuất bằng cờ này: firebase emulators:start --export-on-exit=./saved-data. Nếu bạn sử dụng --import, đường dẫn xuất sẽ mặc định là đường dẫn đó; ví dụ: firebase emulators:start --import=./data-path --export-on-exit. Cuối cùng, nếu muốn, hãy truyền các đường dẫn thư mục khác nhau đến cờ --import--export-on-exit.
--import=import_directory Không bắt buộc. Sử dụng với trình mô phỏng Authentication, Cloud Firestore, Realtime Database hoặc Cloud Storage for Firebase. Nhập dữ liệu đã lưu bằng tuỳ chọn khởi động --export-on-exit hoặc lệnh emulators:export vào một thực thể trình mô phỏng Authentication, Cloud Firestore, Realtime Database hoặc Cloud Storage for Firebase đang chạy. Mọi dữ liệu hiện có trong bộ nhớ trình mô phỏng sẽ bị ghi đè.
emulators:exec scriptpath Chạy tập lệnh tại scriptpath sau khi khởi động trình mô phỏng cho các sản phẩm Firebase được định cấu hình trong firebase.json. Các quy trình của trình mô phỏng sẽ tự động dừng khi tập lệnh chạy xong.
Cờ Nội dung mô tả
--only Không bắt buộc. Giới hạn số lượng trình mô phỏng khởi động. 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 trong số "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 Cloud Functions để bật tính năng gỡ lỗi điểm ngắt của các hàm tại cổng được chỉ định (hoặc cổng mặc định 9229 nếu bỏ qua đối số). Xin lưu ý rằng khi bạn cung cấp cờ này, trình mô phỏng Cloud Functions sẽ chuyển sang chế độ thực thi tuần tự đặc biệt, trong đó các hàm đượ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 hoá việc gỡ lỗi hàm, mặc dù hành vi này khác với việc thực thi song song nhiều quy trình của các hàm trên đám mây.
--export-on-exit= Không bắt buộc. Sử dụng với trình mô phỏng Authentication, Cloud Firestore, Realtime Database hoặc Cloud Storage for Firebase. Hướng dẫn(các) trình mô phỏng xuất dữ liệu sang một thư mục khi quá trình tắt xảy ra, như mô tả cho lệnh emulators:export. Bạn có thể chỉ định thư mục xuất bằng cờ này: firebase emulators:start --export-on-exit=./saved-data. Nếu bạn sử dụng --import, đường dẫn xuất sẽ mặc định là đường dẫn đó; ví dụ: firebase emulators:start --import=./data-path --export-on-exit. Cuối cùng, nếu muốn, hãy truyền các đường dẫn thư mục khác nhau đến cờ --import--export-on-exit.
--import=import_directory Không bắt buộc. Sử dụng với trình mô phỏng Authentication, Cloud Firestore, Realtime Database hoặc Cloud Storage for Firebase. Nhập dữ liệu đã lưu bằng tuỳ chọn khởi động --export-on-exit hoặc lệnh emulators:export vào một thực thể trình mô phỏng Authentication, Cloud Firestore, Realtime Database hoặc Cloud Storage for Firebase đang chạy. Mọi dữ liệu hiện có trong bộ nhớ của trình mô phỏng sẽ bị ghi đè.
--ui Không bắt buộc. Chạy giao diện người dùng của Trình mô phỏng trong quá trình thực thi.

Phương thức firebase emulators:exec thường phù hợp hơn với quy trình tích hợp liên tục.

Xuất và nhập dữ liệu trình mô phỏng

Bạn có thể xuất dữ liệu từ trình mô phỏng Authentication, Cloud Firestore, Realtime DatabaseCloud Storage for Firebase để sử dụng làm tập dữ liệu cơ sở phổ biến, có thể chia sẻ. Bạn có thể nhập các tập dữ liệu này bằng cờ --import, như mô tả ở trên.

emulators:export export_directory

Trình mô phỏng Authentication, Cloud Firestore, Realtime Database hoặc Cloud Storage for Firebase. Xuất dữ liệu từ một thực thể trình mô phỏng Cloud Firestore, Realtime Database hoặc Cloud Storage for Firebase đang chạy. export_directory được chỉ định sẽ được tạo nếu chưa có. Nếu thư mụ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ẽ bị ghi đè. Bạn có thể bỏ qua lời nhắc này bằng cách sử dụng cờ --force. Thư mục xuất chứa một tệp kê khai dữ liệu, firebase-export-metadata.json.

Bạn có thể hướng dẫn trình mô phỏng tự động xuất dữ liệu khi tắt bằng cách sử dụng cờ --export-on-exit được mô tả ở trên.

Tích hợp với hệ thống CI

Chạy hình ảnh Bộ công cụ mô phỏng được đóng gói

Việc cài đặt và định cấu hình Bộ trình mô phỏng với các vùng chứa trong một thiết lập CI thông thường rất đơn giản.

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

Tạo mã thông báo xác thực (chỉ dành cho trình mô phỏng lưu trữ)

Nếu quy trình tích hợp liên tục của bạn dựa vào Firebase Hosting , thì bạn sẽ cần đăng nhập bằng mã thông báo để chạy firebase emulators:exec. Các trình mô phỏng 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ộ; bạn không nên thực hiện việc này 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; hãy đảm bảo mã thông báo được giữ bí mật.

Nếu môi trường CI 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 bản dựng, bạn 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. Giao diện dòng lệnh Firebase sẽ tự động nhận biến môi trường FIREBASE_TOKEN và trình mô phỏng sẽ khởi động đúng cách.

Nếu không còn cách nào khác, bạn chỉ cần đưa mã thông báo vào tập lệnh bản dựng, 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ã hoá cứng này, bạn có thể thêm --token "YOUR_TOKEN_STRING_HERE" vào lệnh firebase emulators:exec.

Sử dụng API REST của Trung tâm trình mô phỏng

Liệt kê các trình mô phỏng đang chạy

Để liệt kê các trình mô phỏng đang chạy, hãy gửi yêu cầu GET đến điểm cuối /emulators của Trung tâm trình mô phỏng.

curl localhost:4400/emulators

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

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

Bật / tắt trình kích hoạt hàm trong nền

Trong một số trường hợp, bạn sẽ cần tạm thời tắt hàm cục bộ và trình kích hoạt tiện ích. Ví dụ: bạn có thể muốn xoá tất cả dữ liệu trong trình mô phỏng Cloud Firestore mà không kích hoạt bất kỳ hàm onDelete nào đang chạy trong trình mô phỏng Cloud Functions hoặc Extensions.

Để tạm thời tắt trình kích hoạt hàm cục bộ, hãy gửi yêu cầu PUT đến điểm cuối /functions/disableBackgroundTriggers của Trình mô phỏng trung tâm.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

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

{
  "enabled": false
}

Để bật trình kích hoạt hàm cục bộ sau khi các trình kích hoạt này bị tắt, hãy gửi yêu cầu PUT đến điểm cuối /functions/enableBackgroundTriggers của Trung tâm trình mô phỏng.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

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

{
  "enabled": true
}

Tích hợp SDK trình mô phỏng

Các bảng trong phần này cho biết trình mô phỏng nào được SDK ứng dụng và SDK quản trị hỗ trợ. Tương lai có nghĩa là tính năng hỗ trợ trình mô phỏng đã được lên kế hoạch nhưng chưa có.

Khả năng sử dụng SDK ứng dụng

Android Nền tảng của Apple Web Giao diện người dùng Firebase
Android
Giao diện người dùng Firebase
iOS
Giao diện người dùng Firebase
Web
Realtime Database 19.4.0 7.2.0 8.0.0 6.4.0 Tương lai Không áp dụng
Cloud Firestore 21.6.0 7.2.0 8.0.0 6.4.0 Tương lai Không áp dụng
Authentication 20.0.0 7.0.0 8.0.0 7.0.0 Tương lai 4.7.2
Cloud Storage for Firebase 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0 Không áp dụng
Cloud Functions 19.1.0 7.2.0 8.0.0 Không áp dụng Không có Không có
Hosting Không có Không có Không có Không có Không có Không có
Extensions Không có Không có Không có Không có Không có Không áp dụng

Khả năng sử dụng SDK dành cho quản trị viên

Điểm Java Python Go
Realtime Database 8.6.0 6.10.0 2.18.0 Tương lai
Cloud Firestore 8.0.0 6.10.0 3.0.0 1.0.0
Authentication 9.3.0 7.2.0 5.0.0 4.2.0
Cloud Storage for Firebase 9.8.0 Tương lai Tương lai Tương lai
Cloud Functions Không áp dụng Không có Không có Không có
Hosting Không có Không có Không có Không có
Extensions Không có Không có Không có Không áp dụng