Next.js Static Export와 GitHub Actions를 통한 제로 비용 서버리스 포트폴리오 구축

I shipped my developer portfolio on GitHub Pages with Next.js static export

MEHTAB RIAZ2026년 4월 19일2분beginner

AI 요약

Context

런타임 서버 비용 제거와 관리 포인트 최소화를 위해 서버리스 정적 호스팅 환경 필요. 특히 GitHub Pages의 Subpath 배포 시 발생하는 Asset 경로 불일치와 정적 파일 참조 문제 해결이 핵심 과제임.

Technical Solution

output: 'export' 설정을 통한 HTML/JS/CSS 기반 Static Site Generation 구조 설계
basePath 및 assetPrefix를 CI 환경의 레포지토리 이름과 동기화하여 Subpath 배포 경로 문제 해결
publicPath() 헬퍼 함수 구현을 통한 로컬 환경과 프로덕션 환경 간의 Asset 참조 일관성 확보
getStaticProps 기반 Build-time Data Fetching을 통해 GitHub API 및 RSS 데이터를 정적 페이지에 주입
JSON 기반 Content Modeling 분리를 통한 JSX 수정 없는 효율적인 콘텐츠 업데이트 구조 구축
SVG Favicon 내 비트맵 Data URI 인라이닝 처리를 통한 Chromium 브라우저 렌더링 이슈 해결

실천 포인트

- GitHub Pages Subpath 배포 시 Next.js의 `basePath`와 `assetPrefix` 설정을 반드시 검토할 것 - 정적 호스팅 환경에서 이미지 최적화가 필요할 경우 `images.unoptimized` 설정 및 외부 CDN 도입 고려 - 콘텐츠 변경 빈도가 높은 페이지는 JSX 내 하드코딩 대신 별도 JSON 파일로 모델링하여 유지보수성 향상

태그

#SSG #CI/CD #Static Export #GitHub Actions #Next.js

원문 읽기