<div id="readability-page-1" class="page"><div><div aria-hidden="false"><a rel="noopener follow" href="/?source=post_page---byline--d6d42ef913ae---------------------------------------"><div><p><img alt="이상문" src="https://miro.medium.com/v2/resize:fill:64:64/1*PdFTYwkEj-ebxhH52VWJ8w.png" width="32" height="32" loading="lazy" data-testid="authorPhoto"></p></div></a></div><p id="ebb6">Firebase의 Firestore 에뮬레이터는 실제 서비스에 영향을 주지 않고도 데이터베이스 로직을 로컬에서 안전하게 개발하고 테스트할 수 있도록 해준다. 이 글에서는 Firestore 에뮬레이터를 로컬에서 설정하고 UI를 통해 상태를 확인하는 방법을 단계별로 정리하고자 한다.</p><h2 id="b6d5">1. Firebase CLI 설치</h2><p id="e40e">Firestore 에뮬레이터를 실행하려면 Firebase CLI가 필요하다.</p><pre><span id="1036">npm install -g firebase-tools</span></pre><p id="f9ce">설치 후 정상적으로 동작하는지 확인한다.</p><pre><span id="8b10">firebase --version</span></pre><h2 id="0ac6">2. Firebase 프로젝트 초기화</h2><p id="01e5">프로젝트 루트 디렉토리에서 아래 명령어를 실행하여 Firebase 설정을 초기화한다.</p><pre><span id="28c1">firebase init</span></pre><h2 id="3eb2">주요 선택 항목:</h2><ul><li id="a6a1"><strong>Emulators</strong>: 선택</li><li id="8655"><strong>Firestore</strong>: 선택</li><li id="16a6"><strong>Emulator UI</strong>: 선택</li><li id="3a0f">포트를 변경하지 않았다면 기본값 사용 (Firestore: 8080, UI: 4000)</li></ul><p id="4682">초기화가 완료되면 <code>firebase.json</code>과 <code>.firebaserc</code> 파일이 생성된다.</p><h2 id="954d">3. firebase.json 설정 예시</h2><p id="9975"><code>firebase.json</code> 파일은 어떤 에뮬레이터를 어떤 포트에서 실행할지 정의한다. 다음은 Firestore와 UI 에뮬레이터를 설정한 예시이다.</p><pre><span id="48af">{<br>  "emulators": {<br>    "firestore": {<br>      "port": 8080<br>    },<br>    "ui": {<br>      "enabled": true,<br>      "port": 4000<br>    }<br>  }<br>}</span></pre><p id="7232">해당 설정이 포함되어 있어야 <code>firebase emulators:start</code> 명령만으로 Firestore와 UI가 함께 실행된다.</p><h2 id="b9f1">4. Firestore 에뮬레이터 및 UI 실행</h2><p id="cd26">에뮬레이터를 실행하려면 아래 명령어를 사용합니다:</p><pre><span id="37a8">firebase emulators:start</span></pre><blockquote><p id="2f37"><em>⚠️ 주의: </em><code><em>--only firestore,ui</em></code><em> 옵션을 사용하면 특정 환경에서는 오류가 발생할 수 있다. 단순히 </em><code><em>firebase emulators:start</em></code><em> 명령만 실행해도 Firestore와 UI가 함께 실행되도록 </em><code><em>firebase.json</em></code><em> 설정이 반영된다.</em></p></blockquote><p id="1186">이 명령어는 Firestore 에뮬레이터와 함께 Emulator UI도 실행한다. UI는 기본적으로 <a href="http://localhost:4000/" rel="noopener ugc nofollow" target="_blank">http://localhost:4000</a> 에서 확인할 수 있다.</p><p id="fed4">에뮬레이터 실행 로그에서 아래 내용을 확인할 수 있다.</p><ul><li id="a332">Firestore가 정상적으로 바인딩 되었는가</li><li id="4431">UI가 정상적으로 기동되었는가</li></ul><h2 id="1ebc">5. FastAPI에서 Firestore 에뮬레이터 연동 예제 (Python)</h2><p id="f489">Python에서 <code>google-cloud-firestore</code> 패키지를 이용하여 FastAPI 애플리케이션 내에서 Firestore 에뮬레이터와 통신하는 예제이다. 로컬 개발 환경과 실제 배포 환경을 자동으로 구분하여 처리할 수 있도록 구성한다.</p><h2 id="c811">요구사항 설치</h2><pre><span id="bded">pip install fastapi uvicorn google-cloud-firestore</span></pre><h2 id="eab3">코드 예제: <code>main.py</code></h2><pre><span id="fc55">from fastapi import FastAPI, Request<br>from google.cloud import firestore<br>from google.cloud.firestore_v1.client import Client<br>import os<p>app = FastAPI()<br># Firestore 클라이언트 초기화<br>if os.environ.get('FIRESTORE_EMULATOR_HOST'):<br>    # 로컬 개발 환경 (에뮬레이터 사용)<br>    from google.auth.credentials import AnonymousCredentials<br>    db = Client(project="my-firestore-app", credentials=AnonymousCredentials())<br>else:<br>    # 배포 환경 (실제 Firestore 사용)<br>    db = firestore.Client(project="my-firestore-app")<br>@app.post("/add")<br>async def add_data(request: Request):<br>    body = await request.json()<br>    doc_ref = db.collection("items").document(body["id"])<br>    doc_ref.set({"name": body["name"]})<br>    return {"status": "saved"}<br>@app.get("/get/{item_id}")<br>async def get_data(item_id: str):<br>    doc = db.collection("items").document(item_id).get()<br>    if doc.exists:<br>        return doc.to_dict()<br>    return {"error": "not found"}</p></span></pre><h2 id="5617">실행 방법</h2><pre><span id="1dda">uvicorn main:app --reload</span></pre><blockquote><p id="f395"><em>위 코드에서는 환경 변수 </em><code><em>FIRESTORE_EMULATOR_HOST</em></code><em>가 설정되어 있으면 로컬 에뮬레이터를, 그렇지 않으면 실제 Firestore를 사용한다. 배포 환경에서는 이 변수를 설정하지 않아야 하며, 로컬 개발 시 </em><code><em>.env</em></code><em> 등을 통해 설정할 수 있다.</em></p></blockquote><h2 id="0d14">6. 주의사항</h2><ul><li id="1e85">에뮬레이터는 로컬 파일 시스템에 데이터를 저장하며, 재시작 시 초기화되지 않으므로 원한다면 <code>--import</code> 및 <code>--export-on-exit</code> 옵션을 사용할 수 있다.</li><li id="95e2"><code>--import=./data</code> 옵션은 지정된 디렉토리에서 이전에 저장한 Firestore 데이터를 불러온다.</li><li id="5329"><code>--export-on-exit=./data</code> 옵션은 에뮬레이터가 종료될 때 현재 데이터를 해당 디렉토리에 자동 저장한다.</li><li id="44ef">이 두 옵션을 함께 사용하면 매 실행 시 데이터를 자동 복원하고 저장할 수 있어 테스트 환경을 지속적으로 유지할 수 있다.</li><li id="6a3c">이 디렉토리는 버전 관리에 포함할 필요가 없으므로 <code>.gitignore</code> 파일에 추가해두는 것이 좋다.</li><li id="d9bc">예시:</li></ul><pre><span id="6968">firebase emulators:start --import=./data --export-on-exit=./data</span></pre><ul><li id="7621">실제 Firebase 프로젝트에 배포되지 않으므로 테스트 중 실수로 데이터를 변경하더라도 안전을 보장할 수 있다.</li></ul><h2 id="e2ca">7. 마무리</h2><p id="21d5">Firestore 에뮬레이터를 활용하면 팀 개발 시에도 백엔드 없이 독립적인 데이터베이스 테스트가 가능하고, 배포 전 로직 검증에 유용할 것이다.</p></div></div>

Stories by 이상문 on Medium

Firebase의 Firestore 에뮬레이터는 실제 서비스에 영향을 주지 않고도 데이터베이스 로직을 로컬에서 안전하게 개발하고 테스트할 수 있도록 해준다. 이 글에서는 Firestore 에뮬레이터를 로컬에서 설정하고 UI를 통해 상태를 확인하는 방법을 단계별로 정리하고자 한다.
1. Firebase CLI 설치
Firestore 에뮬레이터를 실행하려면 Firebase CLI가 필요하다.
npm install -g firebase-tools
설치 후 정상적으로 동작하는지 확인한다.
firebase --version
2. Firebase 프로젝트 초기화
프로젝트 루트 디렉토리에서 아래 명령어를 실행하여 Firebase 설정을 초기화한다.
firebase init
주요 선택 항목:
Emulators: 선택
Firestore: 선택
Emulator UI: 선택
포트를 변경하지 않았다면 기본값 사용 (Firestore: 8080, UI: 4000)
초기화가 완료되면 firebase.json과 .firebaserc 파일이 생성된다.
3. firebase.json 설정 예시
firebase.json 파일은 어떤 에뮬레이터를 어떤 포트에서 실행할지 정의한다. 다음은 Firestore와 UI 에뮬레이터를 설정한 예시이다.
{
  "emulators": {
    "firestore": {
      "port": 8080
    },
    "ui": {
      "enabled": true,
      "port": 4000
    }
  }
}
해당 설정이 포함되어 있어야 firebase emulators:start 명령만으로 Firestore와 UI가 함께 실행된다.
4. Firestore 에뮬레이터 및 UI 실행
에뮬레이터를 실행하려면 아래 명령어를 사용합니다:
firebase emulators:start
⚠️ 주의: --only firestore,ui 옵션을 사용하면 특정 환경에서는 오류가 발생할 수 있다. 단순히 firebase emulators:start 명령만 실행해도 Firestore와 UI가 함께 실행되도록 firebase.json 설정이 반영된다.
이 명령어는 Firestore 에뮬레이터와 함께 Emulator UI도 실행한다. UI는 기본적으로 http://localhost:4000 에서 확인할 수 있다.
에뮬레이터 실행 로그에서 아래 내용을 확인할 수 있다.
Firestore가 정상적으로 바인딩 되었는가
UI가 정상적으로 기동되었는가
5. FastAPI에서 Firestore 에뮬레이터 연동 예제 (Python)
Python에서 google-cloud-firestore 패키지를 이용하여 FastAPI 애플리케이션 내에서 Firestore 에뮬레이터와 통신하는 예제이다. 로컬 개발 환경과 실제 배포 환경을 자동으로 구분하여 처리할 수 있도록 구성한다.
요구사항 설치
pip install fastapi uvicorn google-cloud-firestore
코드 예제: main.py
from fastapi import FastAPI, Request
from google.cloud import firestore
from google.cloud.firestore_v1.client import Client
import os
app = FastAPI()
# Firestore 클라이언트 초기화
if os.environ.get('FIRESTORE_EMULATOR_HOST'):
    # 로컬 개발 환경 (에뮬레이터 사용)
    from google.auth.credentials import AnonymousCredentials
    db = Client(project="my-firestore-app", credentials=AnonymousCredentials())
else:
    # 배포 환경 (실제 Firestore 사용)
    db = firestore.Client(project="my-firestore-app")
@app.post("/add")
async def add_data(request: Request):
    body = await request.json()
    doc_ref = db.collection("items").document(body["id"])
    doc_ref.set({"name": body["name"]})
    return {"status": "saved"}
@app.get("/get/{item_id}")
async def get_data(item_id: str):
    doc = db.collection("items").document(item_id).get()
    if doc.exists:
        return doc.to_dict()
    return {"error": "not found"}
실행 방법
uvicorn main:app --reload
위 코드에서는 환경 변수 FIRESTORE_EMULATOR_HOST가 설정되어 있으면 로컬 에뮬레이터를, 그렇지 않으면 실제 Firestore를 사용한다. 배포 환경에서는 이 변수를 설정하지 않아야 하며, 로컬 개발 시 .env 등을 통해 설정할 수 있다.
6. 주의사항
에뮬레이터는 로컬 파일 시스템에 데이터를 저장하며, 재시작 시 초기화되지 않으므로 원한다면 --import 및 --export-on-exit 옵션을 사용할 수 있다.
--import=./data 옵션은 지정된 디렉토리에서 이전에 저장한 Firestore 데이터를 불러온다.
--export-on-exit=./data 옵션은 에뮬레이터가 종료될 때 현재 데이터를 해당 디렉토리에 자동 저장한다.
이 두 옵션을 함께 사용하면 매 실행 시 데이터를 자동 복원하고 저장할 수 있어 테스트 환경을 지속적으로 유지할 수 있다.
이 디렉토리는 버전 관리에 포함할 필요가 없으므로 .gitignore 파일에 추가해두는 것이 좋다.
예시:
firebase emulators:start --import=./data --export-on-exit=./data
실제 Firebase 프로젝트에 배포되지 않으므로 테스트 중 실수로 데이터를 변경하더라도 안전을 보장할 수 있다.
7. 마무리
Firestore 에뮬레이터를 활용하면 팀 개발 시에도 백엔드 없이 독립적인 데이터베이스 테스트가 가능하고, 배포 전 로직 검증에 유용할 것이다.

Firestore 에뮬레이터를 이용한 로컬 개발 환경 구성 가이드

댓글