로컬 에뮬레이터 도구 모음 설치, 구성, 통합

Firebase 로컬 에뮬레이터 도구 모음은 일회성 프로토타입 세션부터 프로덕션 규모의 지속적 통합 워크플로에 이르기까지 다양한 프로토타입 및 테스트 환경에 설치하고 구성할 수 있습니다.

로컬 에뮬레이터 도구 모음 설치

에뮬레이터 도구 모음을 설치하려면 필요한 사항은 다음과 같습니다.

에뮬레이터 도구 모음을 설치하려면 다음 단계를 따르세요.

  1. Firebase CLI 설치 Firebase CLI를 아직 설치하지 않은 경우 지금 설치합니다. 에뮬레이터 도구 모음을 사용하려면 CLI 버전 8.14.0 이상이 설치되어야 합니다. 다음 명령어를 사용하여 설치한 버전을 확인할 수 있습니다.
    firebase --version
  2. 명령어를 아직 사용하지 않은 경우 화면에 표시되는 메시지에 따라 사용할 제품을 지정하여 현재 작업 디렉터리를 Firebase 프로젝트로 초기화합니다.
    firebase init
  3. 에뮬레이터 도구 모음을 설정합니다. 이 명령어는 원하는 에뮬레이터를 선택하고 해당 에뮬레이터 바이너리 파일을 다운로드하며 기본값이 적절하지 않은 경우 에뮬레이터 포트를 설정할 수 있는 구성 마법사를 시작합니다.
    firebase init emulators

에뮬레이터가 설치되면 Firebase CLI 버전을 업데이트할 때까지 업데이트 확인이 수행되지 않으며 자동 다운로드가 추가로 진행되지 않습니다.

에뮬레이터 도구 모음 구성

필요할 경우 firebase.json 파일에서 에뮬레이터의 네트워크 포트와 보안 규칙 정의 경로를 구성할 수 있습니다.

  • firebase init emulators를 실행하거나 firebase.json을 수동으로 편집하여 에뮬레이터 포트를 변경합니다.
  • firebase.json을 수동으로 편집하여 보안 규칙 정의 경로를 변경합니다.

이러한 설정을 구성하지 않으면 에뮬레이터가 기본 포트를 리슨하며 Cloud Firestore, 실시간 데이터베이스, Firebase용 Cloud Storage 에뮬레이터는 개방형 데이터 보안으로 실행됩니다.

명령어 설명
init emulators 에뮬레이터 초기화 마법사를 시작합니다. 설치할 에뮬레이터를 식별하고 선택적으로 에뮬레이터 포트 설정을 지정합니다. init emulators는 비파괴적이므로 기본값을 수락하면 현재 에뮬레이터 구성이 유지됩니다.

포트 구성

각 에뮬레이터는 선호하는 기본값을 사용하여 머신의 다른 포트에 바인딩됩니다.

에뮬레이터 기본 포트
인증 9099
에뮬레이터 도구 모음 UI 4000
Cloud Functions 5001
Eventarc 9299
실시간 데이터베이스 9000
Cloud Firestore 8080
Firebase용 Cloud Storage 9199
Firebase 호스팅 5000
Pub/Sub 8085

프로젝트 ID 구성

에뮬레이터를 호출하는 방법에 따라 서로 다른 Firebase 프로젝트 ID를 사용하여 에뮬레이터의 여러 인스턴스를 실행하거나 특정 프로젝트 ID의 여러 에뮬레이터 인스턴스를 실행할 수 있습니다. 이러한 경우 에뮬레이터 인스턴스가 별도의 환경에서 실행됩니다.

에뮬레이터 도구 모음 UI, 다양한 제품 에뮬레이터, 특정 에뮬레이터의 실행 중인 모든 인스턴스가 모든 경우에 제대로 통신할 수 있도록 일반적으로 모든 에뮬레이터 호출에 하나의 프로젝트 ID를 설정하는 것이 좋습니다.

로컬 에뮬레이터 도구 모음은 환경에서 여러 프로젝트 ID를 감지하면 경고를 표시하지만 firebase.json에서 singleProjectMode 키를 false로 설정하여 이 동작을 재정의할 수 있습니다.

다음에서 프로젝트 ID 선언의 불일치를 확인하세요.

  • 명령줄의 기본 프로젝트. 기본적으로 프로젝트 ID는 시작 시 firebase init 또는 firebase use로 선택한 프로젝트에서 가져옵니다. 프로젝트 목록을 보고 어떤 프로젝트가 선택되었는지 확인하려면 firebase projects:list를 사용하세요.
  • 규칙 단위 테스트. 일반적으로 프로젝트 ID는 규칙 단위 테스트 라이브러리 메서드 initializeTestEnvironment 또는 initializeTestApp을 호출할 때 지정됩니다.
  • 명령줄의 --project 플래그. Firebase CLI --project 플래그를 전달하면 기본 프로젝트가 재정의됩니다. 플래그 값이 단위 테스트 및 앱 초기화의 프로젝트 ID와 일치하는지 확인해야 합니다.

또한 Apple 플랫폼, Android, 프로젝트를 구성하는 동안 설정한 플랫폼별 프로젝트 ID 구성을 확인합니다.

보안 규칙 구성

에뮬레이터는 firebase.jsondatabase, firestore, storage 구성 키에서 보안 규칙 구성을 가져옵니다.

{
  // 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"
    }
  }
}

자바 옵션 지정

실시간 데이터베이스 에뮬레이터, Cloud Firestore 에뮬레이터, 일부 Firebase용 Cloud Storage 에뮬레이터는 자바를 기반으로 하며 환경 변수 JAVA_TOOL_OPTIONS를 통해 JVM 플래그로 맞춤설정할 수 있습니다.

예를 들어 자바 힙 공간 관련 오류가 발생하면 최대 자바 힙 크기를 4GB로 늘릴 수 있습니다.

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g"와 같이 여러 플래그를 따옴표 안에 공백으로 구분하여 지정할 수 있습니다. 플래그는 에뮬레이터의 자바 기반 구성요소에만 영향을 미치며 에뮬레이터 도구 모음 UI와 같은 Firebase CLI의 다른 부분에는 영향을 미치지 않습니다.

에뮬레이터 시작

에뮬레이터를 시작하여 수동으로 종료하거나 지정된 테스트 스크립트 기간 동안 실행한 후 자동으로 종료되도록 할 수 있습니다.

명령어 설명
emulators:start firebase.json에서 구성된 Firebase 제품의 에뮬레이터를 시작합니다. 에뮬레이터 프로세스는 명시적으로 중지할 때까지 계속 실행됩니다. emulators:start를 호출할 때 에뮬레이터가 아직 설치되지 않은 경우 ~/.cache/firebase/emulators/에 다운로드됩니다.
플래그 설명
--only 선택사항. 시작할 에뮬레이터를 제한합니다. 'auth', 'database', 'firestore', 'functions', 'hosting' 또는 'pubsub' 중 하나 이상을 지정하여 쉼표로 구분된 에뮬레이터 이름 목록을 제공합니다.
--inspect-functions debug_port 선택사항. Cloud Functions 에뮬레이터와 함께 사용하여 지정된 포트 또는 인수가 생략된 경우 기본 포트 9229에서 함수의 중단점 디버깅을 사용합니다. 이 플래그가 제공되면 Cloud Functions 에뮬레이터는 함수가 단일 프로세스에서 순차적(FIFO) 순서로 실행되는 특수 직렬화 실행 모드로 전환됩니다. 이렇게 하면 함수 디버깅이 간소화되지만 동작은 클라우드의 멀티 프로세스 동시 실행과는 다릅니다.
--export-on-exit= 선택사항. 인증, Cloud Firestore, 실시간 데이터베이스 또는 Firebase용 Cloud Storage 에뮬레이터와 함께 사용합니다. emulators:export 명령어에 설명된 대로 종료가 발생하면 데이터를 디렉터리로 내보내도록 에뮬레이터에 지시합니다. 내보내기 디렉터리는 firebase emulators:start --export-on-exit=./saved-data 플래그로 지정할 수 있습니다. --import를 사용하면 내보내기 경로의 기본값이 동일하게 설정됩니다(예: firebase emulators:start --import=./data-path --export-on-exit). 마지막으로 원하는 경우 다른 디렉터리 경로를 --import--export-on-exit 플래그에 전달합니다.
--import=import_directory 선택사항. 인증, Cloud Firestore, 실시간 데이터베이스 또는 Firebase용 Cloud Storage 에뮬레이터와 함께 사용합니다. --export-on-exit 시작 옵션 또는 emulators:export 명령어를 사용하여 저장된 데이터를 실행 중인 인증, Cloud Firestore, 실시간 데이터베이스 또는 Firebase용 Cloud Storage 에뮬레이터 인스턴스로 가져옵니다. 현재 에뮬레이터 메모리에 있는 모든 데이터를 덮어쓰게 됩니다.
emulators:exec scriptpath firebase.json에 구성된 Firebase 제품의 에뮬레이터를 시작한 후 scriptpath에서 스크립트를 실행합니다. 스크립트 실행이 완료되면 에뮬레이터 프로세스가 자동으로 중지됩니다.
플래그 설명
--only 선택사항. 시작할 에뮬레이터를 제한합니다. 'firestore', 'database', 'functions', 'hosting' 또는 'pubsub' 중 하나 이상을 지정하여 쉼표로 구분된 에뮬레이터 이름 목록을 제공합니다.
--inspect-functions debug_port 선택사항. Cloud Functions 에뮬레이터와 함께 사용하여 지정된 포트 또는 인수가 생략된 경우 기본 포트 9229에서 함수의 중단점 디버깅을 사용합니다. 이 플래그가 제공되면 Cloud Functions 에뮬레이터는 함수가 단일 프로세스에서 순차적(FIFO) 순서로 실행되는 특수 직렬화 실행 모드로 전환됩니다. 이렇게 하면 함수 디버깅이 간소화되지만 동작은 클라우드의 멀티 프로세스 동시 실행과는 다릅니다.
--export-on-exit= 선택사항. 인증, Cloud Firestore, 실시간 데이터베이스 또는 Firebase용 Cloud Storage 에뮬레이터와 함께 사용합니다. emulators:export 명령어에 설명된 대로 종료가 발생하면 데이터를 디렉터리로 내보내도록 에뮬레이터에 지시합니다. 내보내기 디렉터리는 firebase emulators:start --export-on-exit=./saved-data 플래그로 지정할 수 있습니다. --import를 사용하면 내보내기 경로의 기본값이 동일하게 설정됩니다(예: firebase emulators:start --import=./data-path --export-on-exit). 마지막으로 원하는 경우 다른 디렉터리 경로를 --import--export-on-exit 플래그에 전달합니다.
--import=import_directory 선택사항. 인증, Cloud Firestore, 실시간 데이터베이스 또는 Firebase용 Cloud Storage 에뮬레이터와 함께 사용합니다. --export-on-exit 시작 옵션 또는 emulators:export 명령어를 사용하여 저장된 데이터를 실행 중인 인증, Cloud Firestore, 실시간 데이터베이스 또는 Firebase용 Cloud Storage 에뮬레이터 인스턴스로 가져옵니다. 현재 에뮬레이터 메모리에 있는 모든 데이터를 덮어쓰게 됩니다.
--ui 선택사항. 실행하는 동안 에뮬레이터 UI를 실행합니다.

firebase emulators:exec 메서드는 일반적으로 지속적 통합 워크플로에 더 적합합니다.

에뮬레이터 데이터 내보내기 및 가져오기

인증, Cloud Firestore, 실시간 데이터베이스, Firebase용 Cloud Storage 에뮬레이터에서 데이터를 내보내 공유 가능한 공통 기준 데이터 세트로 사용할 수 있습니다. 이러한 데이터 세트는 위에서 설명한대로 --import 플래그를 사용하여 가져올 수 있습니다.

emulators:export export_directory

인증, Cloud Firestore, 실시간 데이터베이스 또는 Firebase용 Cloud Storage 에뮬레이터. 실행 중인 Cloud Firestore, 실시간 데이터베이스 또는 Firebase용 Cloud Storage 에뮬레이터 인스턴스에서 데이터를 내보냅니다. 지정된 export_directory가 아직 없으면 새로 생성됩니다. 지정된 디렉터리가 있는 경우 이전 내보내기 데이터를 덮어쓸지 확인하는 메시지가 표시됩니다. --force 플래그를 사용하여 이 메시지를 건너뛸 수 있습니다. 내보내기 디렉터리에는 데이터 매니페스트 파일인 firebase-export-metadata.json이 포함되어 있습니다.

에뮬레이터가 종료되면 위에서 설명한 --export-on-exit 플래그를 사용하여 자동으로 데이터를 내보내도록 지시할 수 있습니다.

CI 시스템과 통합

컨테이너화된 에뮬레이터 도구 모음 이미지 실행

일반적인 CI 설정에서 컨테이너를 사용하여 에뮬레이터 도구 모음을 설치하고 구성하는 방법은 간단합니다.

다음과 같은 몇 가지 문제가 있습니다.

  • JAR 파일은 ~/.cache/firebase/emulators/에 설치되고 캐시됩니다.

    • 이 경로를 CI 캐시 구성에 추가하여 반복 다운로드를 방지할 수 있습니다.
  • 저장소에 firebase.json 파일이 없는 경우 emulators:start 또는 emulators:exec 명령어에 명령줄 인수를 추가하여 시작할 에뮬레이터를 지정해야 합니다. 예를 들면 다음과 같습니다.
    --only functions,firestore

인증 토큰 생성(호스팅 에뮬레이터 전용)

지속적 통합 워크플로가 Firebase 호스팅을 사용하는 경우 firebase emulators:exec를 실행하려면 토큰을 사용하여 로그인해야 합니다. 다른 에뮬레이터에는 로그인이 필요하지 않습니다.

토큰을 생성하려면 로컬 환경에서 firebase login:ci를 실행합니다. 이 작업은 CI 시스템에서 수행하면 안 됩니다. 안내에 따라 인증하세요. 토큰은 빌드 간에 유효하므로 프로젝트당 한 번만 수행하면 됩니다. 토큰은 비밀번호처럼 비밀로 유지해야 합니다.

CI 환경에서 빌드 스크립트에 사용할 수 있는 환경 변수를 지정할 수 있으면 값이 액세스 토큰 문자열인 FIREBASE_TOKEN이라는 환경 변수를 만들면 됩니다. Firebase CLI가 자동으로 FIREBASE_TOKEN 환경 변수를 선택하고 에뮬레이터가 올바르게 시작됩니다.

마지막 수단으로 빌드 스크립트에 토큰을 포함할 수 있지만 신뢰할 수 없는 사용자가 액세스할 수 없도록 해야 합니다. 이 하드 코딩된 방식의 경우 firebase emulators:exec 명령어에 --token "YOUR_TOKEN_STRING_HERE"를 추가할 수 있습니다.

Emulator Hub REST API 사용

실행 중인 에뮬레이터 나열

현재 실행 중인 에뮬레이터를 나열하려면 GET 요청을 에뮬레이터 허브의 /emulators 엔드포인트로 전송합니다.

curl localhost:4400/emulators

결과로 실행 중인 모든 에뮬레이터와 호스트/포트 구성을 나열하는 JSON 객체가 반환됩니다. 예를 들면 다음과 같습니다.

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

백그라운드 함수 트리거 사용 설정/사용 중지

상황에 따라서는 로컬 함수와 확장 프로그램 트리거를 일시적으로 사용 중지해야 할 수 있습니다. 예를 들어 Cloud Functions 또는 확장 프로그램 에뮬레이터에서 실행 중인 onDelete 함수를 트리거하지 않고 Cloud Firestore 에뮬레이터의 모든 데이터를 삭제하려는 경우가 해당합니다.

로컬 함수 트리거를 일시적으로 사용 중지하려면 PUT 요청을 에뮬레이터 허브의 /functions/disableBackgroundTriggers 엔드포인트로 전송합니다.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

결과로 현재 상태를 자세히 설명하는 JSON 객체가 반환됩니다.

{
  "enabled": false
}

로컬 함수 트리거를 사용 중지한 후 사용 설정하려면 PUT 요청을 에뮬레이터 허브의 /functions/enableBackgroundTriggers 엔드포인트로 전송합니다.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

결과로 현재 상태를 자세히 설명하는 JSON 객체가 반환됩니다.

{
  "enabled": true
}

에뮬레이터 SDK 통합

이 섹션의 표는 클라이언트 및 Admin SDK에서 지원하는 에뮬레이터를 나타냅니다. 예정은 에뮬레이터 지원이 예정되어 있지만 아직 사용할 수 없음을 의미합니다.

클라이언트 SDK 가용성

Android Apple 플랫폼 Firebase UI
Android
Firebase UI
iOS
Firebase UI
실시간 데이터베이스 19.4.0 7.2.0 8.0.0 6.4.0 예정 해당 사항 없음
Cloud Firestore 21.6.0 7.2.0 8.0.0 6.4.0 예정 해당 사항 없음
인증 20.0.0 7.0.0 8.0.0 7.0.0 예정 4.7.2
Firebase용 Cloud Storage 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0 해당 사항 없음
Cloud Functions 19.1.0 7.2.0 8.0.0 해당 사항 없음 해당 사항 없음 해당 사항 없음
호스팅 해당 사항 없음 해당 사항 없음 해당 사항 없음 해당 사항 없음 해당 사항 없음 해당 사항 없음
Firebase Extensions 해당 사항 없음 해당 사항 없음 해당 사항 없음 해당 사항 없음 해당 사항 없음 해당 사항 없음

Admin SDK 가용성

노드 자바 Python Go
실시간 데이터베이스 8.6.0 6.10.0 2.18.0 예정
Cloud Firestore 8.0.0 6.10.0 3.0.0 1.0.0
인증 9.3.0 7.2.0 5.0.0 4.2.0
Firebase용 Cloud Storage 9.8.0 예정 예정 예정
Cloud Functions 해당 사항 없음 해당 사항 없음 해당 사항 없음 해당 사항 없음
호스팅 해당 사항 없음 해당 사항 없음 해당 사항 없음 해당 사항 없음
Firebase Extensions 해당 사항 없음 해당 사항 없음 해당 사항 없음 해당 사항 없음