GitHub Pages로 Next.js 프로젝트 배포하기

최근 Next.js 프로젝트를 GitHub Pages에 배포하는 방법에 대해 고민하면서 여러 설정과 배포 방식을 직접 경험해보았습니다. 이번 포스트에서는 Next.js의 정적 내보내기(next export) 기능과 GitHub Actions를 활용하여 자동으로 배포하는 전체 과정을 정리해봅니다.

1. Next.js 정적 내보내기 설정

GitHub Pages는 기본적으로 정적 파일(HTML, CSS, JS)을 서비스합니다.
Next.js는 서버 사이드 렌더링(SSR)이 기본이지만, next export 명령어를 통해 정적 사이트를 생성할 수 있습니다.

1.1 next.config.ts 수정

프로젝트 루트에 next.config.ts 파일을 생성하거나 수정하여 정적 내보내기를 활성화합니다.
필요에 따라 GitHub Pages의 경로에 맞게 basePath와 assetPrefix도 설정합니다.

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",         // 정적 파일 생성을 위한 설정
  basePath: "/FE",          // GitHub Pages에서 사용하는 경로 (저장소명이 FE인 경우)
  assetPrefix: "/FE",       // 정적 에셋 로딩을 위한 경로
};

export default nextConfig;

2. package.json에 export 스크립트 추가

Next.js가 정적 파일을 생성할 수 있도록 스크립트를 추가합니다.

"scripts": {
  "build": "next build",
  "export": "next export",
  "dev": "next dev",
  "start": "next start",
  "lint": "next lint"
}

이후 터미널에서 아래 명령어를 실행하면, 프로젝트 루트에 out 폴더가 생성되고 정적 파일들이 들어갑니다.

npm install
npm run build
npm run export

3. GitHub Actions를 통한 자동 배포 설정

빌드 파일(예: out 폴더)은 git repo에 커밋하지 않고, GitHub Actions를 통해 자동으로 빌드 및 배포할 수 있습니다.
GitHub Actions 워크플로우 파일을 생성하여 main 브랜치에 push할 때마다 자동 배포가 이루어지도록 합니다.

3.1 .github/workflows/deploy.yml 추가

프로젝트 루트의 .github/workflows/ 디렉토리에 deploy.yml 파일을 생성합니다.

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'  # Next.js 요구 사항에 맞는 버전 사용

      - name: Install Dependencies
        run: npm install

      - name: Build and Export
        run: |
          npm run build
          npm run export
          
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./out

이 설정 파일은 main 브랜치에 push될 때마다 다음을 수행합니다:

• 저장소 체크아웃 및 Node.js 설정
• 프로젝트 의존성 설치
• Next.js 빌드 및 정적 내보내기(out 폴더 생성)
• peaceiris/actions-gh-pages 액션을 사용하여 out 폴더의 내용을 gh-pages 브랜치로 배포

참고: GitHub Actions에서는 기본 제공되는 GITHUB_TOKEN을 사용하기 때문에 별도로 토큰 값을 설정할 필요가 없습니다.

4. GitHub Repository 설정

마지막 단계로 GitHub 저장소의 Settings > Pages 메뉴로 이동하여 배포 소스를 설정합니다.

• Source: gh-pages 브랜치를 선택합니다.
• 저장 후, GitHub가 배포를 완료하면
  https://<사용자명>.github.io/<저장소명>/ 주소에서 사이트를 확인할 수 있습니다.

5. 주의사항 및 추가 팁

• 빌드 오류 확인:
  GitHub Actions를 통해 배포하기 전, 로컬 환경에서 빌드, ESLint, 타입 검사를 진행하여 오류가 없는지 반드시 확인하세요.
  예전에 KAKAO_MAP_API와 관련된 오류가 있었는데, 해당 값은 레이아웃 파일에서 export하는 것이 아니라 환경 변수나 별도 설정 파일로 관리해야 합니다.

• 환경 변수 관리:
  API 키 등 민감한 정보는 .env 파일이나 next.config.js의 환경 변수 설정을 통해 관리하여 코드에 직접 노출되지 않도록 합니다.

• basePath와 assetPrefix:
  GitHub Pages에서 프로젝트가 /FE와 같은 서브디렉토리 경로에 배포될 경우, 이 설정이 올바르게 되어 있어야 정적 파일들이 제대로 로드됩니다.

결론

Next.js의 next export 기능과 GitHub Actions를 활용하면 빌드된 정적 파일을 GitHub Pages에 쉽게 배포할 수 있습니다.
이번 경험을 통해 정적 내보내기 설정, GitHub Actions 워크플로우 구성, 그리고 GitHub Pages 설정 등 여러 측면을 점검할 수 있었으며, 덕분에 자동 배포 파이프라인을 구축하는 법을 익힐 수 있었습니다.