[Astro] GitHub Pages 배포

개요

이전 글 레이아웃과 컴포넌트 아키텍처에서 블로그의 구조를 다루었습니다. 이번 글에서는 완성된 블로그를 GitHub Pages에 배포하는 과정을 설명합니다.

Jekyll은 코드를 push하면 GitHub 서버에서 자동으로 빌드/배포해줬지만, Astro는 로컬에서 빌드한 결과물을 직접 배포해야 합니다. 한 단계가 추가되는 셈이지만, 그 대신 빌드 환경을 완전히 제어할 수 있고 모든 플러그인을 자유롭게 사용할 수 있다는 장점이 있습니다.

빌드 파이프라인 이해하기

배포 전에 빌드 과정이 어떻게 진행되는지 이해하면 좋습니다. npm run deploy 한 줄을 실행하면 내부적으로 여러 단계가 자동으로 연쇄 실행됩니다.

npm run deploy
    ↓
1. predeploy: npm run share:sync
    ↓
2. preshare:sync: npm run build
    ↓
3. build: astro build && npx pagefind --site dist
    ↓
4. share:sync: node scripts/share.mjs sync
    ↓
5. deploy: gh-pages -d dist -r ...

이 흐름은 npm의 pre 스크립트 기능을 활용한 것입니다. deploy를 실행하면 자동으로 predeploy가 먼저 실행되고, share:sync를 실행하면 자동으로 preshare:sync가 먼저 실행되는 식입니다. 덕분에 npm run deploy 한 줄만으로 빌드 → 검색 인덱스 생성 → 공유 동기화 → 배포까지 모든 과정이 자동으로 이어집니다.

각 단계 설명

각 단계의 역할을 정리하면 다음과 같습니다.

단계	스크립트	역할
1	`astro build`	Astro 프로젝트를 정적 HTML/CSS/JS로 빌드하여 `dist/` 디렉토리 생성
2	`npx pagefind --site dist`	빌드된 HTML에서 검색 인덱스 생성
3	`share:sync`	RSS 피드 기반으로 소셜 공유 상태 동기화
4	`gh-pages -d dist`	`dist/` 디렉토리를 GitHub Pages에 배포

gh-pages로 배포하기

설치

gh-pages는 빌드된 정적 파일을 GitHub Pages 브랜치(gh-pages)에 자동으로 push해주는 패키지입니다. 빌드 시에만 사용하므로 개발 의존성으로 설치합니다.

npm install -D gh-pages

배포 스크립트

package.json에 다음과 같이 배포 스크립트를 설정합니다.

{
  "scripts": {
    "deploy": "gh-pages -d dist -r [email protected]:posstree/deku.posstree.com.git -t"
  }
}

옵션 설명

각 옵션의 의미는 다음과 같습니다.

옵션	값	설명
`-d dist`	`dist`	배포할 디렉토리. `Astro`의 빌드 출력 디렉토리
`-r`	`git@personal:...`	배포 대상 원격 저장소. SSH 키 별칭(`personal`)을 사용
`-t`	-	숨김 파일(`.nojekyll` 등)도 포함하여 배포

특히 -t 옵션이 중요합니다. 이 옵션이 없으면 .nojekyll 같은 점(.)으로 시작하는 파일이 배포에 포함되지 않아 사이트가 정상 동작하지 않습니다.

배포 실행

설정이 끝나면 다음 명령어 한 줄로 빌드부터 배포까지 모든 과정이 자동으로 실행됩니다.

npm run deploy

커스텀 도메인 설정

CNAME 파일

GitHub Pages에서 username.github.io 대신 커스텀 도메인을 사용하려면 CNAME 파일이 필요합니다. public/CNAME 파일에 사용할 도메인을 한 줄로 기록합니다.

deku.posstree.com

public/ 디렉토리의 파일은 빌드 시 dist/ 디렉토리로 그대로 복사되므로, 별도의 설정 없이 배포 시 자동으로 포함됩니다.

DNS 설정

도메인 관리자(예: Cloudflare, Route53)에서 CNAME 레코드를 설정하여 커스텀 도메인이 GitHub Pages를 가리키도록 합니다.

CNAME  deku.posstree.com  →  username.github.io

.nojekyll 파일의 역할

GitHub Pages에서 Astro를 사용할 때 반드시 알아야 할 파일입니다.

public/.nojekyll

GitHub Pages는 기본적으로 업로드된 파일을 Jekyll로 처리합니다. 그런데 Astro로 빌드하면 _astro/라는 디렉토리가 생기는데, Jekyll은 _로 시작하는 디렉토리를 무시합니다. 결과적으로 CSS와 JavaScript 파일이 로드되지 않아 사이트가 깨져 보입니다.

.nojekyll 파일을 루트에 배치하면 GitHub Pages가 Jekyll 처리를 건너뛰고, 업로드된 파일을 그대로 서빙합니다. 빈 파일이지만 없으면 사이트가 정상 동작하지 않으므로 꼭 포함해야 합니다.

Jekyll 배포와의 비교

Jekyll에서 Astro로 옮기면서 배포 방식이 어떻게 달라졌는지 비교합니다.

항목	Jekyll	Astro
빌드 위치	GitHub Pages 서버에서 빌드	로컬에서 빌드 후 결과물 배포
빌드 시간	~209초 (서버)	~30초 (로컬)
플러그인 제한	GitHub Pages가 허용하는 플러그인만 사용	모든 플러그인 자유롭게 사용
빌드 제어	GitHub에 의존	로컬에서 완전 제어
.nojekyll	불필요	필수
배포 도구	git push만으로 자동 배포	`gh-pages` 패키지 사용

Jekyll은 git push만 하면 되니 초기에는 편했지만, 빌드 환경을 제어할 수 없어 사용할 수 있는 플러그인이 제한적이었습니다. Astro는 로컬 빌드라는 한 단계가 추가되지만, 커스텀 rehype 플러그인이나 Sharp 이미지 변환 같은 고급 기능을 자유롭게 사용할 수 있게 되었습니다.

이전 Jekyll 배포 방법에 대해서는 GitHub Pages 배포 포스트를 참고하세요.