/
/

Firebase App Hosting에 Next.js 프로젝트 배포하기

firebaseApp HostingNext.jsReact
avatar
케요네즈
2025.06.08
·
17 min read

지난 5월, 베타로 제공되던 Firebase의 App Hosting이 드디어 정식 출시되었습니다..!

기존 Firebase Hosting은 정적 콘텐츠 호스팅에 중점을 두어, SSR(서버 사이드 렌더링)을 지원하기 위해서는 별도의 렌더링 서버를 별도 구성해야 하는 번거로움이 있었습니다. 하지만 이제 App Hosting을 통해 Next.js, Angular와 같은 최신 프레임워크로 구축된 웹 애플리케이션을 훨씬 간편하게 배포하고 운영할 수 있게 되었습니다. (아쉽지만 현재 Remix는 공식 지원 범위에 포함되지 않았습니다.)

이 글에서는 Next.js 프로젝트를 Firebase App Hosting으로 배포하는 전체 과정을 단계별로 작성해보려고 합니다!

사전 준비

Next 프로젝트 생성

먼저 배포할 Next.js 애플리케이션을 생성합니다. 이미 프로젝트가 있다면 이 단계는 건너뛰어도 좋습니다. 터미널에서 create-next-app 명령어를 사용합니다.

npx create-next-app@latest [project-name] [options]

명령어를 실행하면, 몇 가지 질문을 통해 프로젝트 설정을 맞춤화할 수 있습니다.

프로젝트 생성이 완료되면 해당 디렉토리로 이동하여 개발 서버를 실행하고, 브라우저에서 http://localhost:3000으로 접속하여 Next.js 앱이 정상적으로 보이는지 확인합니다.

cd [project-name]
npm run dev

Firebase CLI 설치

Firebase 프로젝트를 관리하고 배포하는 데 필수적인 Firebase CLI를 설치합니다. 이미 설치되어 있다면 최신 버전인지 확인하는 것이 좋습니다.

npm install -g firebase-tools

Git에 코드 푸시하기

Git 기반의 간편한 배포 워크플로우

Firebase App Hosting은 GitHub 저장소와 직접 연동하여 git push만으로 빌드부터 배포까지 전 과정을 자동화하는 편리한 Git 기반 워크플로우를 제공합니다. 이를 통해 복잡한 CI/CD 파이프라인을 직접 구축할 필요 없이 코드 개발에만 집중할 수 있습니다.

6602

원격 저장소 연결 및 푸시

Firebase App Hosting은 Git 저장소와 연동하여 작동합니다. 따라서 프로젝트를 Git으로 관리하고 원격 저장소에 푸시해야 합니다.

Firebase 프로젝트 생성

프로젝트 추가

Firebase 콘솔에 접속하여 새 프로젝트를 만들거나 기존 프로젝트를 선택합니다. 프로젝트 이름 지정, 필요하다면 Google 애널리틱스 연동 등의 간단한 단계를 거치면 금방 Firebase 프로젝트가 준비됩니다.

6601

App Hosting 설정 및 GitHub 저장소 연결

App Hosting은 내부적으로 Google Cloud의 서비스(Cloud Run, Cloud Build 등)를 활용하며, 이러한 서비스들은 사용량에 따라 비용이 발생할 수 있습니다. 따라서 App Hosting을 사용하려면 반드시 Firebase 프로젝트를 Blaze 요금제(종량제)로 업그레이드해야 합니다. (Blaze 요금제는 사용한 만큼만 비용을 지불하며, 대부분의 서비스에는 넉넉한 무료 사용량이 포함되어 있어 소규모 프로젝트는 비용 부담이 적을 수 있습니다.)

  1. Firebase 콘솔의 왼쪽 메뉴에서 [빌드(Build) > App Hosting]으로 이동하고 "시작하기" 버튼을 클릭합니다.

  2. 안내에 따라 GitHub 계정을 인증하고 Firebase에 저장소 접근 권한을 부여합니다.

    1. 리전, 저장소, 브랜치 선택:

      • 리전: 애플리케이션을 배포할 리전을 선택합니다. (사용자와 가까울수록 응답 속도에 유리합니다.)

      • 저장소: 배포할 Next.js 프로젝트가 있는 GitHub 저장소를 선택합니다.

      • 브랜치: 배포를 트리거할 브랜치(예: main)를 선택합니다. 이 브랜치에 코드가 푸시될 때마다 자동으로 재배포가 이루어집니다.

    2. 루트 디렉토리 설정:

      • Next.js 프로젝트가 저장소의 루트 디렉토리에 있다면 기본값(/)을 그대로 둡니다.

      • 모노레포 환경과 같이 Next.js 프로젝트가 하위 디렉토리(예: apps/my-next-app)에 위치한다면, 해당 경로를 정확히 입력해야 합니다.

  3. 설정을 검토하고 "완료"를 클릭합니다.

이제 Firebase App Hosting이 GitHub 저장소에서 코드를 가져와 첫 번째 빌드 및 배포를 시작합니다. 이 과정은 몇 분 정도 소요될 수 있으며, 완료되면 대시보드에서 애플리케이션에 접근할 수 있는 고유 URL이 제공됩니다.

로컬 Next 프로젝트에 Firebase 연동 및 구성

Firebase CLI를 사용하여 로컬 프로젝트와 Firebase 프로젝트를 연결하고, App Hosting 관련 설정을 구성합니다.

  1. 터미널에서 Firebase CLI에 로그인 합니다.

    firebase login

  2. 프로젝트 루트 디렉토리에서 Firebase 초기화를 시작합니다.

    firebase init

    • "Are you ready to proceed?"
      → Yes를 입력합니다.

    • "Which Firebase features do you want to set up for this directory?"
      → 키보드 화살표로 이동하여 스페이스바로 "App Hosting"을 선택하고 Enter를 누릅니다.

    • "Please select an option:"
      → Use an existing project를 선택하고, 목록에서 앞서 생성한 Firebase 프로젝트를 선택합니다.

  3. 초기화가 완료되면 프로젝트 루트에 다음과 같은 주요 파일들이 생성되거나 수정됩니다.

    • .firebaserc: 로컬 프로젝트 디렉토리와 연결된 Firebase 프로젝트 ID 및 App Hosting 백엔드 정보를 저장합니다.

    • firebase.json: Firebase 서비스들의 전반적인 설정을 담습니다. App Hosting 관련 설정(배포 소스, 리전 등)이 포함될 수 있습니다.

    • apphosting.yaml: App Hosting 백엔드(내부적으로는 Google Cloud Run 서비스)의 더 세부적인 구성을 정의하는 데 사용됩니다. 런타임 환경, 인스턴스 설정(CPU, 메모리), 빌드 환경 변수, 보안 비밀 참조 등을 상세하게 명시할 수 있습니다.

  4. 생성되거나 수정된 Firebase 관련 설정 파일들을 Git에 커밋하고 원격 저장소에 푸시합니다. 이 푸시를 통해 App Hosting은 변경된 설정을 감지하고 새로운 빌드 및 배포를 진행할 수 있습니다.

Cloud Secret Manager로 환경 변수 안전하게 관리하기

애플리케이션 운영에는 API 키, 데이터베이스 인증 정보 등 민감한 데이터가 필요합니다. 이러한 정보는 코드에 직접 포함하거나 apphosting.yaml에 평문으로 저장하는 대신, Google Cloud Secret Manager를 통해 안전하게 관리하고 App Hosting에서 환경 변수로 주입하는 것이 가장 안전하고 권장되는 방법입니다.

  1. Google Cloud Console에서 보안 비밀 생성:

    • Google Cloud Console에 접속하여 현재 Firebase 프로젝트와 연결된 Google Cloud 프로젝트를 선택합니다.

    • 왼쪽 메뉴에서 [보안(Security) > Secret Manager]로 이동합니다.

    • "보안 비밀 만들기" 버튼을 클릭하고, 보안 비밀의 이름(예: MY_SECRET_EXAMPLE)과 실제 값을 입력하여 생성합니다.

  2. apphosting.yaml에서 보안 비밀 참조 설정:

    • apphosting.yaml 파일의 env 섹션에 환경 변수를 정의하고, secret 키를 사용하여 Secret Manager에 생성한 보안 비밀을 참조하도록 설정합니다.

      # apphosting.yaml
# ... (runConfig 등 기타 설정) ...

env:
  # Secret Manager의 'MY_SECRET_EXAMPLE' 보안 비밀을
  # NEXT_PUBLIC_MY_SECRET_EXAMPLE 환경 변수로 주입
  - variable: NEXT_PUBLIC_MY_SECRET_EXAMPLE
    secret: MY_SECRET_EXAMPLE # Secret Manager에 생성한 보안 비밀 이름
  # - variable: ANOTHER_API_KEY
  #   secret: PROD_API_KEY

      참고: Next.js에서 브라우저 환경(클라이언트 사이드)에서도 접근해야 하는 환경 변수는 반드시 NEXT_PUBLIC_ 접두사를 사용해야 합니다.

  3. Firebase CLI를 통해 App Hosting 백엔드에 보안 비밀 접근 권한 부여:

    firebase apphosting:secrets:grantaccess YOUR_SECRET_NAME --project=YOUR_PROJECT_ID --backend=YOUR_BACKEND_ID

    • YOUR_SECRET_NAME: 접근 권한을 부여할 보안 비밀의 이름입니다.

    • YOUR_PROJECT_ID: 해당 보안 비밀과 App Hosting 백엔드가 속한 Firebase 프로젝트 ID입니다.

    • YOUR_BACKEND_ID: 보안 비밀 접근 권한을 부여받을 App Hosting 백엔드의 고유 ID입니다. (Firebase 콘솔의 App Hosting 섹션 또는 firebase apphosting:backends:list 명령어로 확인 가능)

  4. 보안 비밀 참조 설정을 추가한 apphosting.yaml 파일을 Git에 커밋하고 푸시하여 변경사항을 App Hosting에 반영합니다.

배포 완료 및 환경 변수 사용 확인

이제 모든 설정이 완료되었습니다! App Hosting 대시보드에서 배포 상태를 확인하고, 제공된 URL로 접속하여 애플리케이션이 정상적으로 작동하는지, 그리고 환경 변수가 올바르게 주입되었는지 확인합니다.

# apphosting.yaml

# Settings for Backend (on Cloud Run).
# See https://firebase.google.com/docs/app-hosting/configure#cloud-run
runConfig:
  minInstances: 0
  # maxInstances: 100
  # concurrency: 80
  # cpu: 1
  # memoryMiB: 512

# Environment variables and secrets.
env:
  # Configure environment variables.
  # See https://firebase.google.com/docs/app-hosting/configure#user-defined-environment
  # - variable: MESSAGE
  #   value: Hello world!
  #   availability:
  #     - BUILD
  #     - RUNTIME

  # Grant access to secrets in Cloud Secret Manager.
  # See https://firebase.google.com/docs/app-hosting/configure#secret-parameters
  # - variable: MY_SECRET
  #   secret: mySecretRef

  # Secret 설정 예시
  - variable: NEXT_PUBLIC_MY_SECRET_EXAMPLE
    secret: MY_SECRET_EXAMPLE
// src/app/page.tsx

import Image from "next/image";
import styles from "./page.module.css";

export default function Home() {
  return (
    <div className={styles.page}>
      <main className={styles.main}>
        <Image
          className={styles.logo}
          src="/next.svg"
          alt="Next.js logo"
          width={180}
          height={38}
          priority
        />
        <ol>
          <li>Get started by editing <code>src/app/page.tsx</code>.</li>
          <li>Save and see your changes instantly.</li>

          {/* 환경 변수 값 표시 */}
          <li>{process.env.NEXT_PUBLIC_MY_SECRET_EXAMPLE}</li>
        </ol>
        {/* ... (생략) ... */}
      </main>
    </div>
  );
}
6613

마무리하며

지금까지 Next.js 프로젝트를 생성하고 Firebase와 연동하여 App Hosting으로 배포하는 전체 과정을 함께 살펴봤습니다. Git 저장소 연결부터 Cloud Secret Manager를 활용한 안전한 환경 변수 관리까지, 이제 웹 애플리케이션을 사용자들에게 안정적으로 제공할 준비가 되었습니다.

물론 Vercel은 Next.js의 제작사로서 최적의 개발 경험과 프론트엔드 성능에 강점을 가진 훌륭한 플랫폼입니다. 하지만 Firebase App Hosting은 다음과 같은 뚜렷한 장점을 통해 강력한 대안이 될 수 있습니다.

Firebase 생태계와의 완벽한 시너지

만약 여러분의 애플리케이션이 이미 Firebase 인증(Authentication), Firestore/실시간 데이터베이스, Cloud Functions, Firebase Storage, 또는 Vertex AI for Firebase와 같은 풍부한 Firebase 백엔드 서비스를 활용하고 있거나 활용할 계획이라면, App Hosting은 그 어떤 플랫폼보다 압도적인 통합성과 시너지를 제공합니다. 프론트엔드부터 백엔드, 데이터 저장, AI 기능까지 하나의 일관된 개발 환경과 콘솔에서 관리하며, 데이터 흐름을 간소화하고 전체 시스템의 복잡성을 크게 낮출 수 있습니다.

Google Cloud의 강력하고 안정적인 인프라

Firebase App Hosting의 기반에는 수십 년간 검증된 Google Cloud의 핵심 서비스들(Cloud Run, Cloud Build, Cloud CDN 등)이 자리 잡고 있습니다. 이는 곧 전 세계적인 확장성, 뛰어난 안정성, 그리고 Google 수준의 보안을 의미합니다. 대규모 트래픽을 처리해야 하거나, 엔터프라이즈급의 안정성과 보안이 필요한 애플리케이션이라면 Google Cloud 인프라의 이점을 최대한 누릴 수 있습니다.

Google 백엔드 서비스 연동을 통한 풀스택 개발의 간소화

Vercel이 프론트엔드와 자체 서버리스 함수에 강점을 보인다면, Firebase App Hosting은 Google Cloud의 광범위한 관리형 백엔드 서비스로 나아가는 가장 매끄러운 다리 역할을 합니다. Next.js로 구현된 최신 프론트엔드부터 복잡한 비즈니스 로직을 처리하는 백엔드 서비스까지, Firebase와 Google Cloud라는 일관된 플랫폼 위에서 더욱 손쉽게 풀스택 애플리케이션을 구축하고 확장할 수 있습니다.

결론적으로, 단순히 Next.js 프로젝트를 배포하는 것을 넘어, Firebase 및 Google Cloud의 강력한 생태계 안에서 애플리케이션의 모든 구성요소를 통합하고 확장하고자 한다면 Firebase App Hosting은 좋은 선택이 될 것입니다!

- 컬렉션 아티클