Next.js 배포하기

정적 웹 페이지 배포하기

nextjs
Published

December 9, 2025

Abstract

정적 웹 페이지를 배포하는 방법을 알아보자

Next.js와 GitHub Pages

방식 설명 용도
SSG (Static Site Generation) 빌드 시점에 HTML을 미리 생성 블로그, 문서, 정적 홈페이지
SSR (Server-Side Rendering) 요청 시마다 서버에서 HTML 생성 동적 데이터 필요한 페이지
ISR (Incremental Static Regeneration) SSG + 주기적 재생성 자주 변경되는 정적 사이트

GitHub Pages와 함께 사용하려면 “정적 export” 방식을 써야 합니다. 이는 Next.js 프로젝트를 빌드할 때 모든 페이지를 HTML/CSS/JS 파일로 변환(next build && next export)한 뒤, 그 결과 폴더(out/)를 GitHub Pages에 올리는 방식입니다.

GitHub Pages란?

GitHub가 제공하는 정적 파일 전용 무료 호스팅 서비스입니다.

  • 도메인: username.github.io (username = GitHub 계정명)
  • 비용: 완전 무료
  • 용도: HTML/CSS/JavaScript만 서빙 가능
  • 제한: 데이터베이스, 백엔드 API, 서버 사이드 로직 불가능

GitHub Pages의 특징

  1. 무료 호스팅: GitHub 저장소만 있으면 무료로 무제한 정적 사이트 호스팅 가능
  2. 자동 HTTPS: 모든 GitHub Pages 사이트는 기본적으로 HTTPS(보안 연결) 지원
  3. 커스텀 도메인 지원: DNS 설정으로 자신의 도메인(example.com)을 연결 가능
  4. Git 기반 배포: 저장소에 푸시(push)하면 자동 배포 (추가 설정 없음)
  5. 정적 파일만 지원: Node.js 서버, 데이터베이스 등 백엔드 기능 불가능

저장소 구조

GitHub Pages는 두 가지 배포 방식을 지원합니다.

배포 방식 저장소명 브랜치 배포 폴더
User/Org Pages username.github.io main 루트 또는 /docs
Project Pages 아무 이름 gh-pages 브랜치 루트

Next.js 프로젝트는 보통 out/ (export 결과)를 특정 브랜치(gh-pages)에 배포합니다.

GitHub Actions 상세 소개

GitHub가 제공하는 CI/CD 자동화 서비스로, 저장소의 푸시(push), PR, 특정 시간 등의 이벤트를 트리거로 자동 작업을 실행합니다.

CI/CD 의미

  • CI (Continuous Integration): 코드 푸시 시 자동 테스트, 빌드
  • CD (Continuous Deployment): 빌드 결과를 자동 배포

GitHub Actions 워크플로우 구조

name: Deploy Next.js to GitHub Pages

on:  
push:  
branches:  
- main

jobs:  
build:  
runs-on: ubuntu-latest

steps:  
  - uses: actions/checkout@v3      
  - uses: actions/setup-node@v3  
    with:  
      node-version: '18'  
  - run: npm install  
  - run: npm run build  
  - uses: actions/upload-artifact@v3  
    with:  
      name: out  
      path: out/

각 부분 설명

  • name: 워크플로우 이름
  • on: 트리거 (언제 실행할지) 예를 들어, 예제에서는 main 브랜치에 푸시할 때
  • jobs: 실행할 작업 모음
  • runs-on: 실행 환경 (ubuntu-latest = 최신 Ubuntu Linux)
  • steps: 순차 실행 단계
    • uses: actions/checkout@v3: 저장소 코드 받기 (checkout)
    • uses: actions/setup-node@v3: Node.js 18 설치
    • run: npm install: 의존성 설치 (npm install)
    • run: npm run build: 빌드 실행 (npm run build는 정적 export를 실행하는 명령어)
    • uses: actions/upload-artifact@v3: 생성된 out/ 폴더를 artifacts로 저장

이 워크플로우 덕에, 코드를 푸시하면 자동으로 Next.js 빌드 실행, 정적 export 완료, GitHub Pages에 배포되며, 1-2분 후 https://username.github.io에서 접속 가능합니다.

Next.js 정적 export와 Pages 구조

빌드 시 /blog/1, /blog/2, /blog/3 등을 미리 생성해야 합니다. 그리고 정적 서비스이기 때문에 아래 기능들은 사용할 수 없습니다.

정적 서비스이기 때문에 사용할 수 업는 기능
불가능한 기능 이유
getServerSideProps 서버가 요청 때마다 데이터 생성 (정적 불가)
API Routes 백엔드 API 엔드포인트 (서버 필요)
Image Optimization Next.js 이미지 최적화 (서버 필요)
Dynamic Routes (fallback) 빌드 후 새 경로 생성 불가
Incremental Static Regeneration (ISR) 빌드 후 주기적 재생성 (서버 필요)

만약, 위 기능들이 필요하다면 Vercel, Netlify 같은 Node.js 서버를 지원하는 플랫폼을 써야 합니다.

Next.js GitHub Pages 배포 실전 가이드

Next.js 프로젝트 생성

npx create-next-app@latest sample-nextjs-app --yes

GitHub에 Push

GitHub에 ‘sample-nextjs-app’ 저장소를 생성하고, 코드를 푸시합니다.

git init  
git add .  
git commit -m "Initial commit"  
git branch -M main  
git remote add origin https://github.com/username/sample-nextjs-app.git  
git push -u origin main

GitHub Pages 설정

Repository Settings > Pages > 에서 소스를 “GitHub Actions” 선택합니다.

Next.js를 선택합니다.

설정을 확인하세요.

Commit을 하세요.