본문으로 건너뛰기

Astro framework로 헤드리스 워드프레스 웹사이트를 만들었습니다.

소개

시도하고자 했던 것과 그 이유를 알려주세요.

청각 보조 앱 '깨끗이'의 공식 사이트를 만들었습니다. 요구사항은 단순했는데, 두 개가 정면으로 충돌했습니다.

1) 고객사가 개발자를 안 거치고 직접 글을 올릴 수 있을 것

2) 빠르고, 검색·AI 답변에 잘 걸릴 것

3) (추가) 한국어·영어·일본어 3개 언어

1번만 보면 워드프레스가 답입니다. 고객사가 이미 쓸 줄 알고 에디터도 익숙합니다. 그런데 일반 워드프레스는 방문자가 올 때마다 PHP가 DB를 조회해 HTML을 만들어 내보냅니다. 저렴한 공유 호스팅에서는 이게 그대로 체감 속도가 됩니다. 2번과 충돌합니다.

2번만 보면 정적 사이트 생성기(SSG)가 답입니다. 미리 HTML을 다 구워 두니 빠릅니다. 그런데 글을 올리려면 마크다운 파일을 만들고 git에 커밋해야 합니다. 고객사에게 요구할 수 없습니다.

그래서 둘을 쪼갰습니다

헤드리스(headless) 구성입니다. 워드프레스에서 '머리'(방문자에게 보여주는 화면)를 떼어내고 '몸통'(글 저장소 + 관리자 화면)만 씁니다. 화면은 Astro가 따로 만듭니다.

고객사 ──글 작성──▶ [워드프레스] ──GraphQL──▶ [Astro 빌드]

Hostinger 공유 호스팅 │

(방문자는 여기 안 옴) │ 정적 HTML 생성

▼

[Cloudflare Pages] ──▶ 방문자

이 구조의 핵심은 한 문장으로 요약됩니다.

"워드프레스가 느려도 괜찮습니다. 방문자가 거기로 안 오기 때문입니다."

워드프레스의 응답 속도는 빌드 시간에만 영향을 줍니다. 그래서 워드프레스를 가장 저렴한 축인 Hostinger 공유 호스팅에 두고, 방문자가 닿는 쪽만 CDN에 올렸습니다. 돈을 쓸 자리와 안 써도 되는 자리를 나눈 셈입니다.

다른 선택지를 안 고른 이유

· 일반 워드프레스 + 캐시 플러그인 — 공유 호스팅에서 TTFB가 흔들립니다. 플러그인 충돌·업데이트 관리가 계속 따라옵니다.

· Next.js + 헤드리스 CMS(Sanity 등) — CMS 구독료가 추가되고, 고객사가 새 에디터를 배워야 합니다.

· 노코드 빌더(Webflow·Wix) — 3개 언어 + 구조화 데이터 세밀 제어가 어렵고, 글마다 스키마를 코드로 관리할 수 없습니다.

· Astro + 헤드리스 WP — 고객사는 쓰던 에디터 그대로, 방문자는 정적 HTML, CMS 구독료 0원.

진행 방법

어떤 도구를 사용했고, 어떻게 활용하셨나요?

1. 실제 구성과 스펙

세 층으로 나눠 각각 다른 곳에 올렸습니다.

① 콘텐츠층 — Hostinger 공유 호스팅 (실측값)

· PHP — 8.3.33

· 웹 서버 응답 — Server: hcdn (Hostinger 자체 CDN)

· 엣지 노드 — tok-edge3 (도쿄)

· 업스트림 응답시간 — x-hcdn-upstream-rt: 1.096 (약 1.1초)

· GraphQL 쿼리 응답 — 0.50 ~ 0.69초 (3회 측정)

· 핵심 플러그인 — WPGraphQL, WPGraphQL for Polylang, Polylang

· 비고 — REST 네임스페이스에 hostinger/v1, hostinger-ai-plugin/v1 등 호스팅사 자체 플러그인이 기본 포함

WPGraphQL은 워드프레스에 GraphQL 엔드포인트(/graphql)를 열어 주는 플러그인입니다. REST API 대신 쓰는 이유는 필요한 필드만 한 번에 집어올 수 있어서 빌드할 때 왕복 횟수가 줄기 때문입니다.

다국어는 Polylang + WPGraphQL for Polylang 조합입니다. 후자는 워드프레스 공식 플러그인 저장소 검색에 안 나오고 GitHub(valu-digital/wp-graphql-polylang)에서 zip을 받아 설치해야 했습니다. 이걸 넣어야 GraphQL 쿼리에 where: { language: KO } 같은 언어 필터가 생깁니다.

② 빌드층 — Astro

· Astro 7.0.9 (output: "static", 어댑터 없음)

· Node 22.12.0 / pnpm 11.1.2

· Tailwind CSS 4.3.2 (@tailwindcss/vite)

· 이미지 처리 — sharp 0.34.5 + astro:assets

· 그 외 — @astrojs/sitemap, astro-seo, astro-icon, @playform/compress, node-html-parser

Astro를 고른 이유는 두 가지입니다. 첫째, 기본이 정적 생성 + JS 0바이트입니다. React나 Vue는 쓰지 않으면 번들에 안 들어갑니다. 둘째, 어댑터 없이 순수 정적 출력이 가능해서 Cloudflare Pages에 그냥 올라갑니다. 서버리스 함수가 하나도 필요 없습니다.

③ 배포층 — Cloudflare Pages

GitHub 저장소의 main에 푸시하면 자동 빌드됩니다. 설정은 pnpm build / 출력 dist / NODE_VERSION=22 입니다.

2. 공유 호스팅이 만든 제약, 그리고 그 대응

여기가 이 프로젝트에서 가장 많이 고친 부분입니다.

빌드 한 번에 GraphQL을 여러 번 때립니다(언어 3개 × 글 목록·뉴스 목록 + 상세). 그런데 공유 호스팅은 짧은 시간에 요청이 몰리면 429(Too Many Requests)를 돌려줍니다. 그래서 빌드용 클라이언트를 직접 짰습니다. 핵심은 네 가지입니다.

· 완만한 스로틀 — 요청 사이 최소 간격(기본 250ms)

· 429 전용 처리 — 재시도 횟수를 소비하지 않고 30초 대기 후 다시

· 프로미스 메모이즈 — 같은 쿼리를 동시에 부르는 페이지들이 한 요청을 공유

· 목록 쿼리에만 fallback — 실패해도 빈 배열로 빌드를 통과

참고로 이 구조는 원본 템플릿에서 요청마다 5초를 강제로 쉬게 되어 있었습니다. 글이 100편이면 빌드가 8분을 넘깁니다. 간격을 250ms로 줄이고 메모이즈를 넣어 해결했습니다.

3. 자동배포 — 발행 버튼이 트리거

고객사가 "글 올렸는데 왜 안 떠요?"라고 묻는 상황을 없애야 했습니다. 워드프레스에 mu-plugin을 하나 넣어 발행 전이에만 Cloudflare 배포 훅을 호출합니다.

훅 URL은 저장소에 두지 않고 워드프레스의 wp-config.php에 상수로 넣었습니다. 코드가 공개돼도 아무나 빌드를 돌릴 수 없습니다.

4. 빌드 산출물 스펙 (실측)

· 생성 페이지 — 52개 (3개 언어 + 블로그 9편 + 뉴스 5건 + 분류 페이지)

· 빌드 시간 — 45.83초 (로컬, 전체 재생성)

· 전체 JS — 101.7 KB (11개 파일)

· 그중 최대 — BaseLayout 72.6 KB (스크롤 애니메이션 라이브러리)

· CSS — 3개 파일

· 이미지 — webp 49개

· HTML 압축 — 53개 파일에서 146 KB 절감

결과와 배운 점

배운 점 1 — 한글 슬러그는 캐시 무효화를 깨뜨립니다

Cloudflare Pages에서 퍼센트 인코딩된 경로는 s-maxage=604800(7일)이 걸립니다. 삭제한 글의 한글 URL이 GET으로 계속 200을 반환했습니다.

· 같은 경로도 HEAD는 404, 캐시버스터를 붙인 GET도 404

· 특정 배포 주소(.pages.dev)도 404 → 배포 산출물에는 없고 순수 캐시 잔존

· zone의 Purge Everything으로도 안 지워짐 (Pages 내부 캐시)

· 일반 ASCII 경로는 max-age=0, must-revalidate — 이 문제가 없음

퍼센트 인코딩 경로가 HTML 정책이 아니라 정적 자산 정책(7일)으로 분류된 것으로 보입니다. 그래서 글·카테고리·태그 슬러그를 전부 영문으로 강제했습니다.

아직 못 한 것

· JS 번들 — 101.7 KB 중 72.6 KB가 스크롤 애니메이션. IntersectionObserver + CSS로 바꾸면 약 2 KB입니다.

· 모바일 PageSpeed — 초기 72점. 폰트 자체호스팅과 View Transitions off는 적용했고, 위 JS가 마지막 레버입니다.

· llms.txt — 없음

· 글 페이지 FAQPage — 없음. 9편 모두 FAQ 섹션이 있는데 구조화 데이터로 안 나갑니다.

앞으로의 계획

1) 스크롤 애니메이션 경량화 (72.6 KB → 약 2 KB)

2) llms.txt + 글 페이지 FAQPage 스키마

3) 구글 서치콘솔 등록

4) 구글 애널리틱스 등록

5) 네이버 웹마스터 등록

6) 빙 웹마스터 등록

7) GEO, AEO 최적화 계속 진행

기타 참고 사이트

· WPGraphQL https://www.wpgraphql.com/ · WPGraphQL for Polylang https://github.com/valu-digital/wp-graphql-polylang (워드프레스 플러그인 검색에 안 나옵니다. GitHub에서 zip을 받으세요.) · Astro 공식 문서 https://docs.astro.build/ 특히 astro:assets 의 remotePatterns · 만든 사이트 https://clearsenseaudio.com/

함께 이야기해요 0

로그인하고 댓글을 남겨 주세요

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기