Next.js 블로그 만들기 - 0. 프로젝트 설정 및 배포 | WxNovic

1. Next.js란?

Next.js는 React 기반의 프레임워크로, 서버 사이드 렌더링(SSR)과 정적 사이트 생성(SSG)을 지원하여 성능과 SEO 최적화가 가능합니다. 파일 기반 라우팅, 서버 컴포넌트, API 라우트 등의 기능을 제공하며, React 애플리케이션을 더욱 효율적으로 개발할 수 있도록 돕는 프레임워크입니다.

우리는 블로그를 제작하기 위해 정적 사이트 생성(SSG) 기능이 필요하기 때문에 Next.js를 활용할 것입니다. 직접 구현할 수도 있지만, Next.js가 이미 최적화된 기능을 제공하므로 이를 이용하여 블로그를 제작해 보겠습니다.

먼저, Next.js를 설치하고 실행하는 방법을 살펴보겠습니다.

2. Next.js 설치 및 실행

npx create-next-app@latest my-next-app
cd my-next-app
npm run dev

2-1. Next.js 설치

위 명령어를 실행하면 설치가 완료되며, http://localhost:3000에 접속하면 초기 화면을 확인할 수 있습니다.

install-next-js

2-2. Next.js 실행 결과

Next.js 프로젝트가 정상적으로 실행되면 브라우저에서 기본 화면이 표시됩니다.

next-js-init

3. GitHub Pages란?

GitHub Pages는 GitHub에서 제공하는 정적 웹사이트 호스팅 서비스입니다. 저장소의 코드를 기반으로 웹사이트를 자동으로 배포할 수 있어 블로그, 프로젝트 문서, 포트폴리오 사이트 등을 쉽게 구축할 수 있습니다.

3-1. 주요 특징

무료 호스팅 제공: GitHub 계정만 있으면 무료로 사용 가능
간단한 배포: GitHub 저장소에 코드 푸시만 하면 자동으로 사이트 업데이트
정적 파일 지원: HTML, CSS, JavaScript 등 정적 콘텐츠 배포 가능
커스텀 도메인 지원: 기본적으로 https://<username>.github.io/ URL 제공, 맞춤 도메인 설정 가능

3-2. 기본 사용법

GitHub에서 새 저장소 생성
정적 파일(HTML, CSS, JavaScript) 또는 SSG 프레임워크(Next.js, Jekyll 등)로 생성한 파일 업로드
GitHub Pages 설정에서 브랜치 선택 후 활성화
배포된 사이트 URL 확인

4. GitHub Pages에서 정적 파일을 서비스하기 위한 설정

GitHub Pages에서 정적 파일을 호스팅하려면 저장소를 미리 생성해야 합니다. GitHub에 로그인한 후 새 저장소를 만들고 아래와 같이 설정합니다.

저장소 이름: <username>.github.io

이렇게 설정하면 GitHub Pages의 기본 도메인 구조를 활용할 수 있습니다.

create-repository

5. Next.js를 GitHub Pages에 배포하기 위한 기본 설정

5-1. Next.js 프로젝트의 `next.config.js` 수정

const nextConfig = {
  output: "export",
};

export default nextConfig;

위 설정을 적용하면 빌드 시 out/ 디렉토리가 생성되며, 이 디렉토리를 GitHub Pages에 배포할 수 있습니다.

Note: output: "export" 옵션을 적용하면 Next.js의 렌더링 방식이 SSR(Server-Side Rendering)에서 SSG(Static Site Generation) 방식으로 변경됩니다.

6. Next.js 프로젝트를 GitHub 저장소에 Push

cd my-next-app
git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/<username>/<username>.github.io
git push -u origin main

first-commit

7. gh-pages 패키지를 이용한 배포

GitHub에 블로그 소스코드를 업로드한 후 gh-pages 패키지를 사용하여 간편하게 배포할 수 있습니다.

7-1. gh-pages 패키지 설치

npm install gh-pages --save-dev

7-2. `package.json` 수정 (배포 스크립트 추가)

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "deploy": "npm run build && touch out/.nojekyll && gh-pages -d out"
  }
}

7-3. 배포 실행

아래 명령어를 실행하면 gh-pages 브랜치가 생성되며 GitHub Pages에 배포됩니다.

npm run deploy

배포가 완료되면 GitHub Pages 설정에서 gh-pages 브랜치를 선택해야 합니다.

7-4. GitHub Pages 설정

GitHub 저장소에서 Settings → Pages로 이동하여, Source를 gh-pages 브랜치로 설정하면 배포된 블로그를 확인할 수 있습니다.

github-pages-setting

7-5. 배포된 사이트 확인

https://<username>.github.io/

.nojekyll 파일 추가 (CSS 깨짐 해결)

배포 후 CSS가 적용되지 않는 경우 .nojekyll 파일이 누락되었을 가능성이 있습니다.

nojekyll-not-working

.nojekyll 파일이란? 기본적으로 GitHub Pages는 Jekyll을 사용하며, _next/ 같은 언더스코어(_)로 시작하는 폴더를 무시합니다. Next.js, React, Vue 등의 정적 사이트를 배포할 때 .nojekyll이 없으면 CSS나 JS 파일이 정상적으로 로드되지 않을 수 있습니다. 따라서, out/.nojekyll 파일을 포함하여 배포해야 합니다.

만약 .nojekyll이 push되지 않는다면 아래 명령어를 실행하세요.

git add -f out/.nojekyll
git commit -m "Add .nojekyll"
git push origin gh-pages

또는, GitHub에서 직접 .nojekyll 파일을 추가하는 방법도 있습니다.

add-nojekyll

이제 Next.js와 GitHub Pages를 활용하여 블로그를 간편하게 배포할 수 있습니다! 🚀

다음은 페이지 구성과 마크다운 컨텐츠를 로드하는 방법에 대해 알아보겠습니다.

Next.js 블로그 만들기 - 0. 프로젝트 설정 및 배포