워드프레스 헤드리스 프로젝트와 대처 방법
Source: Dev.to
여러분, 안녕하세요!
우리 팀과 저는 (주니어 백엔드 역할을 맡아) 최근에 GlobeVM(기업용 클라우드·IT·사이버보안 제공업체)를 기존의 모놀리식 워드프레스 사이트에서 헤드리스 아키텍처로 전환하는 작업을 마쳤습니다.
전체 여정, 사용한 기술 스택, 겪었던 큰 어려움들, 그리고 우리가 만든 해결책들을 공유하고자 합니다. 곧 헤드리스 워드프레스를 구축하려는 분이라면, 이 글이 디버깅에 몇 주씩 걸리던 시간을 절약해 줄 수도 있습니다!
프론트엔드: Next.js (App Router), React, Vercel 배포
백엔드: Cloudways에 호스팅된 워드프레스 (순수 헤드리스 CMS 역할)
데이터 구조: Advanced Custom Fields (ACF Pro) + Custom Post Type UI (CPT UI)
SEO: Yoast SEO Premium (REST API 통해)
캐싱: Vercel Edge Cache (ISR) + Cloudways의 Redis Object Cache
개발 및 배포 과정에서 프론트엔드 스택 자체와 워드프레스의 전통적인 기능들에 관련된 여러 문제에 직면했습니다. 여기서 모두 정리하고 공유함으로써 여러분과 함께 각 섹션을 논의하고, 더 특별한 해결책을 찾아볼 수 있으면 좋겠습니다 :)
1️⃣ 기본 워드프레스 REST API 사용 시 문제
처음 시작했을 때 우리는 기본 워드프레스 REST API를 사용했습니다. 블로그 홈 페이지를 구성하기 위해 Next.js 프론트엔드가 8개의 서로 다른 fetch() 호출을 해야 했습니다(게시물, 저자, 카테고리, 태그, ACF 필드 등). 또한 ?_fields=id,title,acf&_embed 같은 지저분한 URL을 사용하고 있었습니다.
해결책
Result: Next.js가 단 하나의
fetch호출만으로 페이지를 로드하게 되었습니다. 페이지가 즉시 표시됩니다.
2️⃣ SVG 아이콘 업로드 차단
우리 서비스 카드 디자인은 커스텀 SVG 아이콘에 크게 의존하고 있었지만, 워드프레스는 보안상의 이유로 기본적으로 SVG 업로드를 차단합니다. 게다가 ACF 이미지 필드를 Next.js와 원활히 연결하는 것도 어려웠습니다.
해결책
(구체적인 구현 내용은 생략했지만, 워드프레스에 SVG 허용 플러그인을 적용하고, ACF 이미지 URL을 정규화하여 Next.js에서 바로 사용할 수 있게 했습니다.)
3️⃣ 댓글 정책 제한
우리는 엄격한 규칙을 적용했습니다: 댓글은 관리자 승인 필요, 그리고 스레드는 1단계 깊이까지만 허용(답글에 대한 답글은 금지).
해결책
워드프레스의
comment_status와threaded_comments설정을 조정하고, REST API에서 댓글 생성 시 검증 로직을 추가했습니다.
4️⃣ 인기 기사 섹션 구현 어려움
조회수 기반의 “Popular Articles” 섹션을 만들고 싶었지만, Next.js는 ISR(Static HTML) 방식을 사용하기 때문에 워드프레스가 사용자가 기사를 읽은 시점을 알 수 없었습니다.
해결책
프론트엔드에서 페이지 뷰 이벤트를 별도의 트래킹 API(예: Google Analytics 혹은 자체 구축한 엔드포인트)로 전송하고, 워드프레스에서 해당 데이터를 받아 ACF 필드에 저장한 뒤, ISR 재생성을 트리거하도록 웹훅을 구성했습니다.
5️⃣ 워드프레스 “프리뷰” 버튼 사용법
프론트엔드가 Vercel에 배포돼 있는 상황에서, 관리자가 워드프레스에서 “Preview” 버튼을 눌러도 실제 미리보기가 보이지 않았습니다.
해결책
Vercel에 프리뷰 전용 라우트를 만들고, 워드프레스의
preview_link를 해당 라우트로 리다이렉트하도록 플러그인을 커스터마이징했습니다. 이제 관리자는 워드프레스 대시보드에서 바로 최신 프리뷰를 확인할 수 있습니다.
6️⃣ 업데이트 시 캐시 동기화 문제
프로덕션에 배포된 후, Next.js는 프론트엔드를 캐시하고 워드프레스는 백엔드를 캐시했습니다. 관리자가 게시물을 수정하면, 워드프레스가 Vercel에 제공하는 JSON이 오래된 상태라 사이트가 바로 업데이트되지 않았습니다.
해결책
ISR 구현 방식에 따라 두 가지 접근법을 사용했습니다.
- On‑Demand Revalidation: 첫 방문자는 캐시된 데이터를 받고, 두 번째 방문자는 최신 데이터를 받도록 설정했습니다. 이렇게 하면 SSG의 속도와 SSR의 실시간성을 동시에 얻을 수 있습니다.
- Time‑Based Revalidation: 일정 시간마다 캐시를 자동으로 갱신하도록 타이머를 설정하고, 워드프레스에서 게시물 업데이트 시 웹훅을 통해 Next.js에 즉시 재검증을 요청했습니다.
두 방법 모두 워드프레스와 Vercel 사이의 캐시 일관성을 유지하는 데 효과적이었습니다.
NOTE: 여기서 말하는 ISR은 “Incremental Static Regeneration”을 의미합니다. 구현 방식은 On‑Demand와 Time‑Revalidation 두 가지가 있으며, 각각의 핵심 포인트는 위에 설명한 대로입니다.
7️⃣ Yoast SEO 태그 주입 한계
헤드리스 환경에서는 Yoast가 자동으로 <title>, <meta> 태그 등을 삽입해 주지 않으므로, 직접 REST API를 통해 필요한 SEO 데이터를 받아와야 합니다.
해결책
Yoast SEO Premium의 REST 엔드포인트를 호출해 메타 정보를 JSON 형태로 받아오고, Next.js 페이지 컴포넌트에서
next/head를 이용해 동적으로 삽입했습니다.
8️⃣ 헤드리스 워드프레스 구축 시 핵심 마인드셋
헤드리스 워드프레스 사이트를 만든다는 것은 단순히 fetch()를 사용하는 것이 아니라, 워드프레스를 데이터베이스 역할에만 국한하고, REST API 아키텍처를 완전히 통제하는 것을 의미합니다.
📚 참고할 만한 대규모 프로젝트
아래와 같은 대형 사이트들도 헤드리스 워드프레스를 활용하고 있으니, 구현 아이디어를 얻는 데 도움이 될 것입니다.
여러분의 프로젝트에 도움이 되길 바랍니다! 🙏