[🛠] 다국어 블로그 빌드 시간을 21분에서 1분대로 줄이기

✨ GPT-5.5의 요약 　

다국어 확장 뒤 20분을 넘기던 Jekyll 빌드를 profile 기준으로 추적해, 반복 렌더링과 전체 사이트 스캔을 걷어내며 1분 50초까지 줄인 기록.

앞선 /devlog/github-pages-blog/github-pages-blog-english-version-lessons/에서 블로그에 다국어 운영 구조를 붙였다.

처음에는 이게 꽤 뿌듯했다.

ko, en, ja, zh-Hans, es, pt-BR, fr, id.

글도 있고, 메뉴도 있고, hreflang도 있고, 조회수도 공유된다. 겉으로는 꽤 그럴듯한 다국어 블로그가 됐다.

그런데 바로 다른 문제가 튀어나왔다.

빌드가 너무 오래 걸렸다.

처음 production build는 이랬다.

done in 1311.791 seconds

21분 52초.

이건 단순 블로그에서 나올 수 있을 만한 수치가 아니다. 글 하나 고치고 빌드가 20분 넘게 걸리면, 나중에는 글을 쓰는 것보다 빌드를 기다리는 시간이 더 길어진다.

처음에는 단순히 “글이 8개 언어가 됐으니까 느려졌겠지”라고 생각할 수도 있었다.

하지만 그건 너무 성급한 결론이었다.

페이지 수가 늘어난 건 맞다. 그래도 20분대까지 가는 건 뭔가 더 있다. 그래서 이번에는 감으로 고치지 않고 jekyll build --profile을 켰다.

첫 번째 범인: 달력 JSON을 모든 페이지에 박고 있었다

먼저 _site 크기를 봤다.

_site: 1.2G
HTML total: 약 840MB

정적 블로그 HTML이 840MB.

말이 안 됐다.

대표 글 하나를 열어보니 바로 이유가 보였다. 사이드바 달력이 모든 글 페이지마다 해당 언어의 전체 글 목록 JSON을 inline으로 넣고 있었다.

<script type="application/json" data-calendar-posts>
[
  ...
]
</script>

그뿐만 아니었다.

달력 fallback 목록을 만들 때 날짜마다 전체 글 목록을 다시 훑고 있었다. 조건에 맞지 않는 글도 Liquid 공백으로 대량 출력됐다. 보이는 화면은 작았는데, HTML 내부에는 거대한 공백과 반복 목록이 숨어 있었다.

이건 기능 문제가 아니라 구조 문제였다.

달력은 서버가 완성형 HTML로 매 페이지마다 만들 필요가 없었다. 이미 JS가 달력을 동적으로 그릴 수 있었다. 그러면 서버는 현재 월의 기본 뼈대와 데이터 파일 경로만 주면 된다.

그래서 언어별 달력 데이터를 별도 JSON 파일로 뺐다.

/assets/data/calendar-posts-ko.json
/assets/data/calendar-posts-en.json
/assets/data/calendar-posts-ja.json
/assets/data/calendar-posts-zh-Hans.json
/assets/data/calendar-posts-es.json
/assets/data/calendar-posts-pt-BR.json
/assets/data/calendar-posts-fr.json
/assets/data/calendar-posts-id.json

그리고 페이지에는 이 정도만 남겼다.

data-calendar-posts-src="/assets/data/calendar-posts-en.json"

결과는 바로 줄었다.

1311.791초 -> 745.273초

절반 가까이 줄었지만, 아직 길었다.

이때 알았다.

달력은 큰 범인이었지만, 유일한 범인은 아니었다.

두 번째 범인: 메뉴 통계를 8만 번 계산하고 있었다

다음 profile이 더 노골적이었다.

_includes/sidebar-nav-stats.html  81120 calls  173.084s
_includes/masthead.html            2704 calls  319.860s
_includes/seo.html                 2704 calls  119.985s
sitemap.xml                           1 call   117.495s

여기서 제일 웃긴 건 sidebar-nav-stats.html이었다.

이 include는 사이드바 카테고리 옆에 글 수와 최신 글 시간을 붙이는 작은 조각이다.

예를 들면 이런 거다.

Daily Review (310) 1 days ago
Devlog (24) 2 days ago

그런데 이 작은 조각이 호출될 때마다 전체 글 목록을 다시 정렬하고, 다시 필터링하고 있었다.

언어별 메뉴 항목마다.

페이지마다.

데스크톱 사이드바와 모바일 메뉴에서 또.

결과적으로 81,120번 호출됐다.

이 값은 사실 페이지마다 새로 계산할 필요가 없다. 같은 언어와 같은 메뉴 URL이면 결과가 똑같다. 그래서 jekyll-include-cache의 include_cached로 바꿨다.

{% include_cached sidebar-nav-stats.html url=child.url lang=current_lang %}

그러자 호출 수가 이렇게 바뀌었다.

81120 calls -> 210 calls
173초 -> 0.4초

이건 거의 버그를 잡은 수준이었다.

세 번째 범인: 언어 링크를 만들려고 전체 사이트를 계속 훑었다

다국어 전환을 붙이면서 masthead, seo, sitemap에 이런 로직이 들어갔다.

이 언어 URL이 실제로 존재하는가?

의도는 맞았다.

존재하지 않는 번역 URL을 hreflang이나 언어 전환 메뉴에 넣으면 안 된다. 그래서 처음에는 모든 페이지와 모든 collection 문서를 돌면서 URL 존재 여부를 확인했다.

문제는 이걸 모든 페이지에서 반복했다는 점이다.

2704 pages * site.pages scan * translated collections scan

이건 다국어 사이트가 커질수록 계속 악화되는 구조다.

그래서 방식을 바꿨다.

이미 이 블로그의 번역 URL은 규칙이 있다.

/some/post/
/en/some/post/
/ja/some/post/
...

그리고 예외는 따로 데이터로 관리하면 된다.

이번에 번역이 아직 보류된 세션 회고 글은 _data/i18n_pending.yml에 넣었다.

entries:
  - source_url: /devlog/github-pages-blog/github-pages-blog-english-version-lessons/
    locales:
      - en
      - ja
      - zh-Hans
      - es
      - pt-BR
      - fr
      - id

이렇게 하니 일반 글은 prefix 규칙으로 연결하고, 보류 글은 다른 언어 홈으로 fallback한다. 전체 사이트 스캔은 하지 않는다.

결과는 컸다.

masthead: 319.860초 -> 9.882초
seo:      119.985초 -> 7.181초
sitemap:  117.495초 -> 4.633초

그리고 최종 빌드는 이렇게 끝났다.

done in 110.344 seconds

21분 52초에서 1분 50초.

이 정도면 아직 빠른 블로그라고 말하기는 어렵지만, 최소한 “빌드가 너무 무서워서 글을 못 쓰는” 상태는 벗어났다.

고치면서 조심한 것

이번 최적화는 속도만 보면 쉬워 보인다.

하지만 진짜 조심해야 했던 건 기능이 깨지는 쪽이었다.

특히 다국어 사이트에서는 빌드가 빨라졌다고 좋아하다가 이런 문제가 생길 수 있다.

언어 전환 링크가 404로 감
hreflang이 존재하지 않는 URL을 가리킴
보류 중인 번역 글이 검색엔진에 alternate로 노출됨
모바일에서 About/언어 버튼이 다시 안 보임
달력이 빈 상태로 남음

그래서 마지막에는 브라우저와 자동 검사를 같이 돌렸다.

확인한 것은 이랬다.

production build 성공
영어 여행글의 8개 언어 전환 링크 정상
hreflang 8개 언어 + x-default 정상
번역 보류 글은 다른 언어 홈으로 fallback
모바일에서 About, 🇺🇸English, 달력 표시 정상
대표 다국어 URL 200
소스 포스트 2481개 렌더링 구조 전수 확인
달력 JSON 파싱 확인
i18n post coverage errors: 0

사람 눈으로 2481개 글을 하나씩 읽은 건 아니다.

하지만 최소한 “출력 파일이 있는가”, “글 구조가 렌더링됐는가”, “언어 링크가 깨지지 않는가”, “달력 데이터가 존재하는가”는 전수 자동 검사로 확인했다.

이게 이번 작업의 핵심이었다.

빌드 최적화는 속도만 줄이는 일이 아니라, 기존 기능의 계약을 다시 명시하는 일이다.

이번에 배운 것

Jekyll은 정적 사이트 생성기라서 단순해 보인다.

하지만 Liquid 안에서 전체 사이트를 계속 훑기 시작하면, 정적 사이트도 충분히 무거워진다.

특히 다국어 구조에서는 작은 비효율이 바로 배수로 커진다.

페이지 수 * 언어 수 * 메뉴 수 * 전체 글 수

이런 곱셈이 숨어 있으면 나중에 갑자기 빌드가 터진다.

이번에 배운 건 단순하다.

첫째, 페이지마다 같은 데이터를 inline으로 반복하지 않는다.

둘째, 같은 입력이면 include를 캐시한다.

셋째, URL 존재 여부를 확인하겠다고 모든 페이지에서 전체 사이트를 스캔하지 않는다.

넷째, 예외는 감으로 처리하지 말고 데이터로 둔다.

다섯째, 최적화 후에는 기능 계약을 자동 검사로 확인한다.

이 블로그는 이제 단순한 개인 블로그에서 조금씩 시스템이 되고 있다.

그게 좋기도 하고, 피곤하기도 하다.

하지만 적어도 이번에는 피곤한 쪽이 의미가 있었다.

21분 넘게 기다리던 빌드를 1분대로 끌어내린 건, 체감상 꽤 큰 전환점이었다.

이제 다국어 블로그를 계속 키울 수 있는 최소한의 숨통은 생겼다.