Astro 블로그 빌드가 느릴 때, OG 이미지 캐시로 줄이는 방법

Astro 블로그를 직접 운영하다 보면 처음에는 잘 안 보이다가,
글이 늘면서 갑자기 신경 쓰이는 문제가 있다.

바로 빌드 시간이다.

특히 글마다 OG 이미지를 자동 생성하고 있다면 더 그렇다.

처음에는 몇 개 안 되니까 괜찮다.
그런데 글이 100개, 200개가 되면 이야기가 달라진다.

모든 글 읽기
→ 모든 OG 이미지 생성
→ 모든 페이지 빌드
→ 배포

이 흐름이면 매번 똑같은 PNG를 다시 만들게 된다.

그런데 생각해보면 이상하다.

제목과 설명이 안 바뀐 글의 OG 이미지는 매번 새로 만들 필요가 없다.

느린 이유는 이미지 생성이 반복되기 때문이다

Astro 자체 빌드도 시간이 들지만,
OG 이미지 생성은 별도의 비용이 있다.

보통은 이런 도구가 들어간다.

• Satori
• Resvg
• Sharp
• Canvas 계열 렌더링

이런 작업은 단순 HTML 생성보다 무겁다.

그래서 글마다 PNG를 다시 만들면 빌드 시간이 쉽게 늘어난다.

예를 들어 글이 200개라면:

200 posts
200 OG image render
200 PNG write

이 작업이 매번 반복된다.

하지만 실제로 매번 바뀌는 글은 보통 1~2개다.

캐시 기준은 파일명이 아니라 내용이어야 한다

처음에는 이렇게 생각하기 쉽다.

og-cache/{slug}.png 있으면 재사용

이 방식도 나쁘지는 않다.
하지만 글 제목이나 설명이 바뀌었는데 이미지가 그대로 남을 수 있다.

그래서 더 안전한 방식은 내용 기준 캐시다.

예:

cache key = hash(title + description + date + template version)

이렇게 하면 제목이나 설명이 바뀌면 캐시 키도 바뀐다.
반대로 아무것도 바뀌지 않은 글은 기존 이미지를 그대로 쓴다.

템플릿 버전도 캐시에 넣어야 한다

여기서 자주 놓치는 게 있다.

OG 이미지 디자인을 바꿨을 때다.

예를 들어:

• 배경색 변경
• 폰트 크기 변경
• 로고 추가
• 레이아웃 수정

이런 변경은 글 frontmatter가 바뀐 것은 아니다.
하지만 이미지는 다시 만들어야 한다.

그래서 캐시 키에 template version을 넣는 게 좋다.

OG_TEMPLATE_VERSION=2

이 값을 바꾸면 전체 OG 이미지를 새 템플릿 기준으로 다시 만들 수 있다.

GitHub Actions에서는 캐시 저장소를 따로 본다

로컬에서 캐시가 잘 된다고 끝이 아니다.

GitHub Actions는 매번 깨끗한 환경에서 시작한다.
그래서 캐시를 유지하려면 Actions cache를 써야 한다.

개념은 이렇다.

restore cache
→ build
→ 새 OG 이미지만 생성
→ save cache

즉, dist에 들어갈 최종 결과물과 og-cache는 역할이 다르다.

• dist: 배포 결과물
• og-cache: 다음 빌드를 빠르게 하기 위한 중간 산출물

이 둘을 섞으면 관리가 애매해진다.

build 폴더를 git에 넣는 방식은 조심해야 한다

가끔 이런 생각도 든다.

build 결과물을 main 브랜치에 같이 커밋하면 빠르지 않을까?

가능은 하다.
하지만 보통은 추천하지 않는다.

이유는 간단하다.

• 빌드 결과물이 커밋마다 크게 늘어남
• 실제 소스 변경과 생성물 변경이 섞임
• 리뷰가 어려워짐
• 충돌이 생기기 쉬움

정적 사이트 배포는 보통 소스와 결과물을 분리하는 게 낫다.

GitHub Pages라면:

main = source
gh-pages 또는 Pages artifact = build output
cache = Actions cache

이 구조가 깔끔하다.

로컬과 Actions 캐시는 따로 생각한다

또 하나 헷갈리는 지점이 있다.

로컬에서도 OG 이미지가 생성되고,
GitHub Actions에서도 생성된다.

그럼 두 번 관리해야 하나?

답은 반쯤 그렇다.

로컬 캐시
  = 개발 중 빠른 확인용

Actions 캐시
  = 배포 빌드 시간 단축용

둘은 같은 개념이지만 저장 위치가 다르다.

로컬 캐시를 git에 올릴 필요는 없다.
Actions cache가 배포 환경에서 따로 보관해주면 된다.

구현할 때 남기면 좋은 로그

캐시는 눈에 잘 안 보이기 때문에 로그가 중요하다.

예:

[og] cache hit slug=...
[og] cache miss slug=...
[og] generated slug=...
[og] copied from cache slug=...

이 정도만 있어도 빌드가 빨라졌는지 감이 온다.

특히 처음 한 번은 느리고,
두 번째부터 빨라지는 게 정상이다.

first build  = cache warm-up
second build = cache reuse

이걸 모르고 첫 빌드만 보면 캐시가 안 먹는 것처럼 보일 수 있다.

오늘 정리

Astro 블로그에서 OG 이미지를 자동 생성한다면,
글이 늘수록 빌드 시간이 늘어나는 건 자연스럽다.

하지만 모든 이미지를 매번 다시 만들 필요는 없다.

좋은 흐름은 이렇다.

글 메타데이터 hash 계산
→ 캐시 존재 확인
→ 있으면 재사용
→ 없으면 생성
→ Actions cache에 저장

이렇게 하면 새 글이나 바뀐 글만 이미지 생성 비용을 치르게 된다.

한 줄 요약

Astro 블로그 OG 이미지는 배포 결과물이 아니라 빌드 중간 산출물로 보고, 내용 기반 캐시를 적용해야 글이 늘어도 빌드 시간이 덜 늘어난다.