Seongyu's Blog

Next.js의 정적 내보내기(Static Exports) 기능과 GitHub Actions를 활용해, 마크다운 파일만 작성하면 자동으로 배포되는 개인 블로그를 구축하는 방법을 알아봅니다.

개요

이 글에서는 다음을 다룹니다.

Next.js 프로젝트를 정적 사이트(Static Site)로 구성하는 방법
main브랜치에 푸쉬하면 자동으로 배포하는 GitHub Actions 파이프라인 구축
posts/ 폴더에 작성한 마크다운을 HTML로 변환해 라우팅하기

Github Blog란?

GitHub Pages는 GitHub 저장소에 있는 정적 파일(HTML, CSS, JS)을 웹사이트로 호스팅해주는 무료 서비스입니다. 이 프로젝트는 main 브랜치에 코드를 푸시하면, GitHub Actions가 자동으로 Next.js 프로젝트를 정적 파일로 빌드하고 그 결과물을 GitHub Pages에 배포하는 방식으로 동작합니다.

GitHub Pages vs Vercel

항목	GitHub Pages	Vercel
비용	무료	무료 플랜 제공 (제한 존재)
호스팅 방식	정적 파일만 호스팅 가능	정적 파일 + 서버리스 함수(SSR, ISR) 지원
배포	GitHub Actions로 직접 설정	Next.js에 최적화된 자동 배포
특징	Git 저장소와 완벽하게 통합	Next.js의 모든 기능(SSR, ISR 등) 활용 가능

정적 블로그만 운영한다면 GitHub Pages로 충분하며, 더 복잡한 동적 기능이 필요하다면 Vercel이 좋은 대안이 될 수 있습니다.

Next.js로 Github Blog 배포하기

사전 준비

Node.js와 npm이 설치되어 있어야 합니다.
GitHub 저장소가 준비되어 있어야 합니다.
Next.js 프로젝트가 있어야 합니다.

Static Exports 설정

next.config.ts에 정적 내보내기를 활성화합니다.

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
  trailingSlash: true,
  images: { unoptimized: true },
  basePath: "",
  assetPrefix: "",
};

export default nextConfig;

GitHub Actions로 자동 배포 (요약)

main 브랜치에 푸시하면 자동으로:

의존성 설치 → 빌드(out/) → Pages 아티팩트 업로드 → GitHub Pages 배포
트리거: push(main), 수동 실행(workflow_dispatch) 지원

최소 구성 예시는 아래와 같습니다(실제 워크플로우와 동일한 단계로 동작):

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [main] # main 브랜치에 푸시될 때 실행
  workflow_dispatch: # 수동 실행 버튼 추가

# 워크플로우에 필요한 권한 설정
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  # 빌드 작업
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "npm"
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./out

  # 배포 작업
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/deploy-pages@v4

Markdown 포스트 작성 규칙

posts/tech/*.md 와 같이 파일을 생성하면 /tech/*.md 경로로 접근할 수 있게 됩니다. 각 마크다운 파일의 최상단에는 Frontmatter라는 형식으로 메타데이터를 작성합니다.

---
title: "포스트 제목"
date: "2025-08-18"
---

여기에 본문을 작성합니다.

필드 설명:

필드	예시	설명
`title`	"Next.js로 만드는 Github Blog"	목록/본문 제목에 사용
`date`	"2025-08-18"	yyyy-mm-dd 형식, 정렬/표시에 사용

장점과 단점

장점

뛰어난 개발 경험: Next.js의 편리한 파일 기반 라우팅과 빠른 개발 환경을 그대로 사용할 수 있습니다.
완전 자동화된 배포: git push 명령어 하나로 글 발행이 완료됩니다.
무료 운영: 호스팅 비용이 전혀 들지 않습니다.

단점

동적 기능 제약: 서버사이드 렌더링(SSR)이나 API Routes 같은 서버 기능은 사용할 수 없습니다. 모든 페이지는 빌드 시점에 생성됩니다.
빌드 시간: 포스트 개수가 수백, 수천 개로 늘어나면 빌드 시간이 길어질 수 있습니다.

결론

Next.js + GitHub Pages 조합은 정적 블로그에 최적화되어 있습니다. 마크다운으로 글을 쓰고 Git에 푸시하면, 액션이 자동으로 빌드/배포해주므로 운영이 매우 간단합니다.

Next.js와 GitHub Actions로 나만의 자동화 블로그 만들기

개요