[Astro] Jekyll에서 Astro로 마이그레이션한 이유

개요

이 블로그는 2018년부터 Jekyll로 운영해왔습니다. Jekyll은 Ruby 기반의 정적 사이트 생성기로, GitHub Pages와의 자연스러운 통합 덕분에 많은 개발자 블로그에서 사용되고 있습니다.

하지만 포스트가 늘어나고 플러그인이 많아지면서 빌드 속도가 급격히 느려지는 문제를 겪었고, 결국 2026년 2월에 Astro로 전면 마이그레이션을 결정했습니다.

이번 글에서는 왜 Jekyll에서 Astro로 옮기게 되었는지, 그 배경과 이유를 공유합니다.

Jekyll의 한계

빌드 속도 문제

Jekyll로 블로그를 운영하면서 가장 큰 문제는 빌드 속도였습니다. 포스트가 늘어나고, 다국어(일본어/한국어/영어) 지원과 다양한 플러그인을 사용하면서 빌드 시간이 급격히 증가했습니다.

bundle exec jekyll serve

위 명령어로 로컬에서 글을 확인할 때, 209초(약 3분 30초)를 기다려야 하는 상황이 되었습니다. 이전 블로그 포스트(블로그 미리보기를 빠르게)에서 limit_posts 설정과 minify 플러그인 비활성화로 50초까지 줄인 적이 있지만, 근본적인 해결책은 아니었습니다.

# _config-dev.yml
limit_posts: 3
jekyll-minifier:
  remove_spaces_inside_tags: false
  remove_multi_spaces: false
  remove_comments: false
  compress_css: false
  compress_javascript: false
  compress_json: false

이렇게 설정해도 50초라는 시간이 걸렸고, 글을 수정할 때마다 이 시간을 기다려야 했습니다.

Ruby 의존성 관리의 어려움

Jekyll은 Ruby 기반이기 때문에 Ruby 버전 관리, Bundler, Gem 의존성 등을 함께 관리해야 합니다. 프론트엔드 개발자로서 일상적으로 사용하는 Node.js/npm 생태계와 분리된 환경을 유지하는 것은 번거로운 일이었습니다.

Liquid 템플릿의 한계

Jekyll의 Liquid 템플릿 엔진은 단순한 블로그에는 충분하지만, 복잡한 로직이나 컴포넌트 재사용이 필요한 경우에는 제한적입니다. 특히 다국어 지원, 동적 메타 태그, 구조화된 데이터(JSON-LD) 등을 구현할 때 코드가 복잡해지는 경향이 있었습니다.

대안 검토

Jekyll에서 벗어나기로 결정한 후, 여러 정적 사이트 생성기를 검토했습니다.

Hugo

장점: Go 기반으로 빌드 속도가 매우 빠름
단점: Go 템플릿 문법이 직관적이지 않고, 프론트엔드 생태계와의 통합이 제한적

Gatsby

장점: React 기반, 풍부한 플러그인 생태계
단점: GraphQL 학습 필요, 빌드 시간이 프로젝트 규모에 비례해 느려짐, 생태계 활성도 저하

Next.js

장점: React 기반, 서버 사이드 렌더링(SSR) 지원, 활발한 생태계
단점: 블로그에는 과도한 기능, 정적 사이트용으로는 설정이 복잡, 불필요한 JavaScript 번들

Astro

장점: Zero JS by default, Vite 기반 빠른 개발 서버, Content Collections, 마크다운 중심, 다양한 프레임워크 통합 가능
단점: 비교적 새로운 프레임워크 (하지만 활발한 커뮤니티)

Astro를 선택한 이유

여러 대안을 검토한 결과, Astro가 이 블로그의 요구사항에 가장 적합하다고 판단했습니다.

1. Zero JavaScript by Default

Astro는 기본적으로 클라이언트에 JavaScript를 전송하지 않습니다. 블로그는 대부분 정적 콘텐츠이므로, 불필요한 JavaScript 번들 없이 순수 HTML/CSS만으로 빠르게 로딩되는 것이 이상적입니다.

2. Vite 기반의 빠른 개발 서버

Vite를 기반으로 한 개발 서버는 HMR(Hot Module Replacement)을 지원하여, 파일을 수정하면 즉시 브라우저에 반영됩니다. Jekyll에서 50~209초를 기다렸던 것과 비교하면 혁신적인 개선입니다.

3. Content Collections

블로그 포스트를 작성할 때, 각 마크다운 파일의 상단에는 제목, 설명, 날짜 같은 메타 정보(frontmatter)를 작성합니다. Jekyll에서는 이 정보에 오타가 있거나 필수 항목이 빠져도 빌드가 그냥 진행되어, 배포 후에야 문제를 발견하는 경우가 있었습니다.

Astro의 Content Collections는 이 문제를 해결해줍니다. 각 필드의 타입(문자열, 날짜, 불리언 등)과 필수 여부를 미리 정의해두면, 빌드 시점에 자동으로 검증하여 잘못된 데이터가 있으면 에러로 알려줍니다. 이 검증 규칙을 정의하는 데 Zod라는 TypeScript 검증 라이브러리를 사용합니다.

예를 들어, 아래와 같이 “블로그 포스트에는 반드시 title(문자열), lang(ja/ko/en 중 하나), date(날짜) 등이 있어야 한다”고 정의할 수 있습니다.

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content' }),
  schema: z.object({
    title: z.string(),           // 필수, 문자열
    description: z.string(),     // 필수, 문자열
    lang: z.enum(['ja', 'ko', 'en']), // 필수, 3개 중 하나
    category: z.string(),        // 필수, 문자열
    permalink: z.string(),       // 필수, 문자열
    date: z.coerce.date(),       // 필수, 날짜
    // ...
  }),
});

만약 마크다운 파일에서 title을 빠뜨리거나, lang에 'kr'처럼 잘못된 값을 넣으면 빌드가 실패하면서 어떤 파일의 어떤 필드가 잘못되었는지 정확히 알려줍니다. 덕분에 실수를 배포 전에 미리 잡을 수 있습니다.

4. 마크다운 중심의 워크플로우

기존 Jekyll 블로그의 마크다운 파일을 거의 그대로 사용할 수 있었습니다. rehype/remark 플러그인을 통해 마크다운 처리를 세밀하게 커스터마이징할 수 있는 점도 큰 장점입니다.

5. Node.js 생태계

npm으로 모든 의존성을 관리하므로, Ruby/Bundler를 별도로 관리할 필요가 없습니다. 프론트엔드 개발자에게 익숙한 환경에서 블로그를 운영할 수 있습니다.

마이그레이션 결과

빌드 시간 비교

마이그레이션의 가장 큰 동기였던 빌드 속도부터 살펴보겠습니다.

항목	Jekyll	Astro
전체 빌드	~209초	~30초
개발 서버 시작	~50초 (최적화 후)	~2초
파일 수정 반영	전체 리빌드 필요	HMR 즉시 반영

전체 빌드 시간이 209초에서 30초로, 약 7배 빨라졌습니다. 하지만 체감상 가장 큰 변화는 개발 서버입니다. Jekyll에서는 글 하나를 수정하고 확인하려면 최소 50초를 기다려야 했지만, Astro에서는 저장하는 즉시 브라우저에 반영됩니다. 글을 쓰는 흐름이 끊기지 않게 된 것이 가장 만족스러운 부분입니다.

주요 개선 사항

빌드 속도 외에도 Astro로 옮기면서 여러 부분이 개선되었습니다.

빌드 속도: 위에서 살펴본 대로, 전체 빌드와 개발 서버 모두 극적으로 빨라졌습니다.
개발 경험: Vite 기반 HMR 덕분에 코드를 수정하면 브라우저가 즉시 업데이트됩니다. 새로고침조차 필요 없는 경우가 대부분입니다.
타입 안전성: Content Collections의 Zod 스키마 검증으로, frontmatter에 오타가 있거나 필수 필드가 빠지면 빌드 단계에서 바로 에러를 알려줍니다. 배포 후에 문제를 발견하는 일이 사라졌습니다.
이미지 최적화: Sharp를 이용한 커스텀 플러그인으로 이미지를 AVIF/WebP 형식으로 자동 변환합니다. 별도의 수작업 없이 빌드 시 알아서 최적화된 이미지가 생성됩니다.
검색 기능: Pagefind를 도입하여 서버 없이도 빠른 전문 검색이 가능해졌습니다. Jekyll에서는 JSON 파일 기반의 느린 검색을 사용했었습니다.
코드 하이라이팅: Shiki를 이용한 서버 사이드 코드 하이라이팅으로, 별도 CSS 없이도 VS Code 수준의 정확한 구문 강조가 적용됩니다.