Astro framework로 헤드리스 워드프레스 웹사이트를 만들었습니다.
2026.10.08
소개
시도하고자 했던 것과 그 이유를 알려주세요.
청각 보조 앱 '깨끗이'의 공식 사이트를 만들었습니다. 요구사항은 단순했는데, 두 개가 정면으로 충돌했습니다.
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/


