이 페이지에서는 Firebase JavaScript SDK를 사용할 때 발생할 수 있는 JavaScript 문제에 관한 팁과 문제 해결 방법을 제공합니다.
다른 문제가 있거나 문제가 표시되지 않나요? Firebase 전체 FAQ 또는 제품별 FAQ를 살펴보려면 기본 Firebase FAQ를 확인하세요.
Firebase JavaScript SDK GitHub 저장소에서 보고된 문제 및 문제 해결의 최신 목록을 확인하고 직접 문제를 제출할 수도 있습니다.
Node.js 구성의 Admin SDK가 Firebase JavaScript SDK와 호환되지 않음
Node.js용 Firebase Admin SDK와 Firebase JavaScript SDK는 인터페이스, 클래스 또는 함수 정의를 공유하지 않는 별개의 구현입니다. Admin SDK 객체의 인스턴스는 Firebase JavaScript SDK 함수와 호환되지 않습니다.
예를 들어 Firebase JavaScript SDK getDatabase 함수에 전달된 Admin SDK의 FirebaseApp 인스턴스는 다음 오류를 발생시킵니다.
TypeError: Cannot read properties of undefined (reading 'getProvider')
at _getProvider
at getDatabase
이는 Realtime Database뿐만 아니라 전체 Firebase JavaScript SDK API 노출 영역에 적용됩니다.
반대 방향의 사용에도 마찬가지입니다. Node.js용 Firebase Admin SDK와 함께 Cloud Firestore JS SDK의 Timestamp 유형을 사용하려고 하면 유사한 오류가 발생합니다.
충돌하는 버전의 Firebase JavaScript SDK를 사용하지 않음
프로젝트에서 종속 항목으로 구성된 상호 충돌하는 여러 버전의 Firebase JavaScript SDK는 SDK 인스턴스가 SDK 패키지 간에 전달될 때 런타임 오류를 일으킵니다. 예를 들어 일치하지 않는 버전의 FirebaseApp와 함께 Data Connect 라이브러리를 사용하면 다음과 같은 오류가 발생합니다.
Error: Component data-connect has not been registered yet
이 문제는 일반적으로 일부 Firebase SDK 패키지의 종속 항목 업데이트로 인해 발생합니다. 이러한 상황은 자동 종속 항목 업데이트 도구가 프로젝트의 yarn.lock 또는 package-lock.json 파일 내 Firebase SDK 종속 항목의 하위 집합을 변경할 때 자주 발생합니다. 여러 Firebase JavaScript SDK가 서로 상호 운용되므로 다양한 버전의 SDK를 사용하면 런타임 비호환성이 발생합니다.
이 문제를 해결하려면 프로젝트에서 node_modules/ 디렉터리와 yarn.lock (yarn의 경우) 또는 package-lock.json (npm의 경우)를 삭제하고 종속 항목을 다시 설치합니다.
오류가 계속되면 npm ls 명령어를 사용하여 문제를 추가로 디버그합니다. 이렇게 하면 프로젝트의 종속 항목이 로깅되므로 충돌하는 firebase 모듈 버전을 식별할 수 있습니다.
예를 들어 다음 로그는 package-using-older-firebase가 충돌하는 버전의 Firebase JavaScript SDK를 가져오는 것을 보여줍니다.
$ npm ls firebase --all
your-app@0.0.0
├── firebase@11.2.0
├─┬ @angular/fire@19.0.0
│ ├── firebase@11.2.0 deduped
│ └─┬ rxfire@6.1.0
│ └── firebase@10.14.1 deduped
└─┬ package-using-older-firebase@0.1.0
└─── firebase@10.14.1
앱에서 CJS와 ESM의 require 및 import 문을 혼합하여 오류가 발생할 수도 있습니다. 이렇게 하면 각각 다른 Firebase JavaScript SDK 인스턴스가 여러 개 생성되어 Firebase JavaScript SDK 상호 운용성이 손상됩니다.
이 시나리오를 디버그하려면 선택한 번들러의 상세 수준을 높입니다. 예를 들어 이 용도로 esbuild analyze 플래그를 사용할 수 있습니다.
서비스 워커가 번들로 묶여 있는지 확인
서비스 워커는 나머지 웹 앱과는 별도의 파이프라인에서 빌드되는 경우가 많으며 Webpack과 같은 번들러의 기본 구성에는 포함되지 않습니다.
서비스 워커 내에서 Firebase JavaScript SDK의 모듈식 버전을 사용하는 경우 서비스 워커 소스 파일을 포함하도록 앱 번들러를 구성해야 합니다. 다음 예에서는 npx를 사용하여 프로젝트의 src 디렉터리에 firebase-sw.js 서비스 워커를 번들로 묶습니다.
npx esbuild ./src/firebase-sw.js --bundle --minify --main-fields=webworker,browser,module,main,default --outfile=public/firebase-sw.js
번들로 묶이지 않은 서비스 워커가 서비스 워커를 지원하지 않는 ES 모듈 또는 서비스 워커 범위에 없는 파일을 가져오면 서비스 워커 활성화가 실패합니다. 이러한 오류는 표시되지 않고 디버그하기 어려운 경우가 있습니다.
Firebase JavaScript SDK의 모듈식 버전을 앱에 번들로 묶는 방법에 관한 자세한 내용은 Firebase와 함께 모듈 번들러 사용을 참고하세요.
또는 CDN에서 compat
Firebase JavaScript SDK 번들을 가져와 번들링할 필요가 없도록 할 수 있습니다.
// Give the service worker access to Firebase Messaging.
// Replace 10.13.2 with the version of the Firebase JS SDK you're using
// in your app.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.js');
// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
...
});
// Retrieve an instance of Firebase Messaging so that it can handle
// background messages.
const messaging = firebase.messaging();
서버 측 렌더링을 사용할 때 FirebaseServerApp 사용
Firebase JavaScript SDK는 원래 브라우저 환경에서 실행되도록 설계되었습니다. 서버 측 렌더링 (SSR) 프레임워크가 도입되면서 SDK 사용이 새로운 런타임 환경으로 이동합니다. 이러한 런타임은 웹브라우저에서 제공하는 도구와 API의 하위 집합을 제공합니다.
예를 들어 일부 Firebase SDK에는 브라우저 전용 API인 IndexedDB를 사용한 데이터 캐싱이 필요합니다. Firebase 인증에서는 헤드리스 서버 환경에서는 불가능한 특정 로그인 과정에서 사용자 상호작용이 필요할 수 있습니다. App Check는 App Check 토큰을 만들기 전에 브라우저 휴리스틱을 사용하여 사용자를 확인합니다.
이러한 새로운 환경에서 SDK를 사용할 때는 클라이언트 측에서 수집된 데이터로 SSR Firebase 인스턴스를 미리 로드하는 수단을 제공하는 FirebaseApp의 새로운 변형인 FirebaseServerApp를 사용하세요.
FirebaseServerApp는 다음 두 가지 매개변수를 지원합니다.
- 인증 ID 토큰: 제공된 경우 Firebase 인증은 이전에 인증된 사용자를 자동으로 로그인하여 CSR/SSR 구분을 넘어 세션을 확장할 수 있습니다.
- 앱 체크 토큰: 제공된 경우 App Check 클라이언트(브라우저 환경 외부에서는 지원되지 않음)의 인스턴스를 초기화할 필요 없이 다른 Firebase SDK에서 토큰을 사용합니다. 이렇게 하면 App Check가 사용 설정된 제품(예: Cloud Functions, Data Connect, Cloud Firestore, Realtime Database, Vertex AI)에 대한 SSR 지원이 차단 해제됩니다.
Next.js에서 FirebaseServerApp를 사용하는 예시는 FirebaseServerApp으로 SSR 앱 개발 간소화를 참고하세요.