블로그: GitHub Pages로 블로그 띄우기

블로그: GitHub Pages로 블로그 띄우기에 대해 "왜?"라고 물으면 답할 수 있으신가요?

\n\n> 블로그: GitHub Pages로 블로그 띄우기에 대해 "왜?"라고 물으면 답할 수 있으신가요?\n블로그를 만들겠다고 마음먹은 건 좋았는데, 제일 먼저 든 생각이 "이걸 어디에 올리지?"였습니다.

AWS? Vercel? Netlify? 선택지가 너무 많아서 오히려 고민이 됐는데, 결국 GitHub Pages 를 선택했습니다. 이유는 단순합니다 — 무료고, GitHub 레포 하나면 끝이고, 커스텀 도메인도 붙일 수 있으니까요.

기술 스택

시작하기 전에 제 블로그의 기술 스택을 간단히 정리하겠습니다.

구분	내용
빌드 도구	Vite
프레임워크	React 19
배포	GitHub Pages
배포 도구	gh-pages (npm)

Vite + React 조합이 아니면 설정이 좀 달라질 수 있으니 참고해주세요.

배포 스크립트 세팅

GitHub Pages에 올리려면 빌드 결과물(dist 폴더)을 gh-pages 브랜치에 푸시해야 합니다. 이걸 수동으로 하면 미칠 것 같아서 gh-pages라는 npm 패키지를 썼습니다.

BASH

npm install --save-dev gh-pages

그리고 package.json에 스크립트를 추가합니다.

JSON

{
  "scripts": {
    "dev": "vite --host",
    "build": "vite build && node scripts/generate-sitemap.js && node scripts/generate-rss.js && node scripts/prerender.js",
    "deploy": "gh-pages -d dist -t"
  }
}

build가 좀 긴데, 나중에 SEO 관련 글에서 자세히 다루겠습니다. 일단 핵심은 vite build로 dist 폴더를 만들고, gh-pages -d dist -t로 그걸 GitHub Pages 브랜치에 올리는 구조입니다.

-t 옵션은 dotfile(.으로 시작하는 파일)도 포함시키는 건데, .nojekyll 파일 때문에 필요합니다. 이거 빠지면 GitHub Pages가 Jekyll로 처리하려다가 에셋 경로가 꼬입니다.

배포 확인

BASH

npm run build
npm run deploy

이 두 줄이면 끝입니다. 실행 후 체크할 것:

GitHub 레포에 gh-pages 브랜치가 생겼는지
그 브랜치 안에 index.html이랑 assets/ 폴더가 있는지

확인됐으면 https://{계정}.github.io/{레포이름}으로 접속해보세요. 잘 뜨면 성공입니다.

근데 저는 안 떴습니다.

트러블슈팅: 404

배포하고 메인 페이지는 뜨는데, 다른 페이지로 이동하거나 새로고침하면 404가 뜹니다. SPA의 고질적인 문제입니다.

GitHub Pages는 정적 파일 서버라서, /posts/어쩌구로 요청이 오면 실제로 그 경로에 HTML 파일이 있어야 합니다. 근데 SPA는 모든 라우팅을 index.html 하나에서 처리하니까, 서버 입장에서는 "그런 파일 없는데?" 하고 404를 내뱉는 거죠.

BrowserRouter basename 설정

커스텀 도메인을 쓰면 basename은 /로 두면 됩니다.

JSX

<BrowserRouter basename="/">
    <App />
</BrowserRouter>

만약 계정.github.io/레포이름 형태로 서브 경로에 배포한다면, basename을 레포 이름으로 맞춰야 합니다. 이걸 안 하면 라우터가 경로를 잘못 읽어서 전부 404입니다.

`<a>` 대신 `<Link>` 사용

리액트 라우터를 쓰는 SPA에서 내부 이동에 <a> 태그를 쓰면 브라우저가 페이지를 새로 요청합니다. 그러면 또 404죠. 내부 라우팅은 반드시 리액트 라우터의 <Link>를 써야 합니다.

이건 기본적인 건데, 의외로 놓치기 쉽습니다.

커스텀 도메인 연결

계정.github.io로도 충분하지만, 개인 도메인을 붙이고 싶었습니다. 제 경우엔 bak-libra26.co.kr을 사용합니다.

1. 도메인 구매

가비아, 닷네임코리아, Cloudflare 등 어디서든 상관없습니다. 저는 호스팅케이알에서 샀습니다.

2. GitHub Pages 설정

레포지토리 Settings → Pages로 가서:

Custom domain 에 도메인 입력 후 저장
SSL 인증서 발급 완료되면 Enforce HTTPS 체크

3. CNAME 파일 추가

GitHub Pages에서 커스텀 도메인을 설정하면 레포에 CNAME 파일이 자동으로 생기는데, gh-pages로 배포할 때마다 날아갑니다. 그래서 프로젝트의 public/ 폴더에 직접 넣어둡니다.

TEXT

bak-libra26.co.kr

public/ 안에 넣어두면 Vite가 빌드할 때 dist/ 루트에 복사해주니까, 배포할 때마다 CNAME이 같이 올라갑니다.

4. DNS A 레코드 설정

도메인 업체의 DNS 설정에서 A 레코드를 추가합니다.