WordPressEscape

홈 / 가이드

워크벤치

528,854개 WordPress 페이지를 Hugo로 이전하기: 엔지니어링 노트

2026년 5월, 같은 그룹의 사내 자매 사이트인 Unlimited Charters를 WordPress에서 Hugo로 이전하며 작성한 실무 노트입니다. 비즈니스 관점의 요약은 사례 연구에 담았고, 여기서는 실제 작업을 맡은 분들에게 필요한 내용을 다룹니다. 50만 페이지 규모에서 무엇이 문제를 일으켰는지, 어떤 명령어가 발목을 잡았는지, 그리고 이제 규모와 관계없이 모든 사이트에 적용하는 점검 항목을 정리했습니다.

읽는 데 8분 9개 섹션 검색 상위 노출을 위해 설계
이 페이지에서
  1. 배경
  2. 콘텐츠 작업 전 템플릿 인벤토리 작성
  3. 파티션 빌드와 파일 시스템의 함정
  4. 템플릿 변경과 전체 콘텐츠 적용으로 진행한 성능 개선
  5. 효과가 컸던 Cloudflare 설정
  6. 스키마 및 SEO 세부 사항
  7. 절대 놓치면 안 되는 리드 수집
  8. 다시 진행한다면 달리 할 일
  9. 출처 및 추가 자료
  10. 자주 묻는 질문
빠른 답변

이 규모에서는 문제의 핵심이 Hugo 자체보다는 파일 시스템과 작업 프로세스에 있습니다. 빌드 파티션을 나누고, 임시 보관 콘텐츠를 Hugo의 content 마운트 외부에 두며, 같은 디렉터리에서 두 개의 이동 작업을 동시에 실행하지 않아야 합니다. 또한 모든 수정은 템플릿 변경과 전체 콘텐츠 대상 스크립트 실행을 한 쌍으로 처리해야 합니다. 성능 개선 효과가 가장 컸던 항목은 이미지 크기 지정, 동기식 중요 CSS, 지연 로딩하지 않은 LCP 이미지, 공간을 미리 확보한 지연 로딩 인용 위젯, Cloudflare Email Obfuscation 비활성화였습니다.

01

배경

Unlimited Charters는 WordPressEscape와 같은 그룹이 소유한 사이트로, 이번 작업은 전체 서버 접근 권한을 바탕으로 진행한 자체 테스트 마이그레이션이었습니다. 사이트에는 50만 개가 조금 넘는 URL이 있었으며, 대부분 템플릿 기반 지역 페이지였고 허브 페이지, 선박 페이지, 블로그도 포함되어 있었습니다. 목표는 기존 경로를 모두 유지하면서 정적 파일로 빌드한 Hugo 사이트를 Cloudflare 뒤에서 제공하는 것이었습니다.

02

콘텐츠 작업 전 템플릿 인벤토리 작성

먼저 URL 패턴이 아니라 해당 페이지를 렌더링하는 WordPress 템플릿을 기준으로 URL을 그룹화했습니다. 각 그룹마다 Hugo 레이아웃으로 다시 구축할지, 아니면 당분간 WordPress 출력 결과를 정적 스냅샷으로 제공할지 결정했습니다. 트래픽이 많은 그룹부터 재구축하고 특이한 페이지는 스냅샷으로 처리하니, 긴 꼬리처럼 남은 맞춤형 페이지 때문에 전체 프로젝트가 지연되는 일을 피할 수 있었습니다.

알아두어야 할 함정도 있습니다. WordPress에서 URL 경로가 항상 post_name 슬러그와 일치하는 것은 아닙니다. 상위 페이지, 사용자 지정 rewrite 규칙, 오래된 가져오기 데이터 때문에 슬러그와 다른 경로가 만들어질 수 있으므로, 경로는 데이터베이스가 아니라 크롤링 결과에서 가져와야 합니다.

03

파티션 빌드와 파일 시스템의 함정

모든 페이지를 한 번에 렌더링하면 시간이 오래 걸리고, 사소한 변경에도 매번 큰 비용이 들었습니다. 그래서 빌드하지 않을 소스 파일을 임시 보관 장소로 옮기고, 일부만 빌드한 뒤 배포하고, 다시 복원하는 방식으로 작업을 나눴습니다. 이 과정에서 네 가지 함정 때문에 시간이 많이 소요됐습니다.

  1. 임시 보관 장소는 Hugo의 content 마운트 외부에 있어야 합니다. 마운트된 content 디렉터리 아래 어디에든 보관하면 Hugo가 여전히 모든 파일을 순회하므로 파티션의 이점이 사라집니다.
  2. rsync --exclude=index.html는 최상위 파일만이 아니라 모든 깊이의 index.html을 제외합니다. 패턴을 고정하려면 --exclude=/index.html을 사용해야 합니다.
  3. 같은 디렉터리에서 두 개의 이동 작업을 동시에 실행하면 디렉터리가 중첩됩니다. 두 개의 복원 프로세스가 서로 경쟁하면서 약 367,000개의 디렉터리가 한 단계 더 깊게 만들어졌습니다. 빌드 결과물을 제공하는 운영 환경에는 문제가 없었고, 단일 스크립트로 이동 작업을 수행해 구조를 평탄화했습니다. 디렉터리의 소유 프로세스는 하나로 제한하고, 잠금으로 이를 강제해야 합니다.
  4. 이 규모에서는 mv dir/* target/이 실패합니다. 인자 목록이 너무 길어지기 때문입니다. 대신 find ... -exec mv -t target {} +을 사용해야 합니다.
# 전체를 다시 빌드하지 않고 일부 페이지만 렌더링
flock /tmp/uc-content.lock bash -c '
  mv content/migrated/* ../stash/            # content 마운트 외부에 보관
  for s in $(cat targets.txt); do mv ../stash/$s content/migrated/; done
  hugo --minify -d ../staged
  find ../stash -mindepth 1 -maxdepth 1 -exec mv -t content/migrated/ {} +
'
04

템플릿 변경과 전체 콘텐츠 적용으로 진행한 성능 개선

모든 수정은 두 단계로 진행했습니다. 향후 빌드가 올바르게 생성되도록 Hugo 템플릿을 수정하고, 전체를 다시 빌드하지 않아도 바로 배포할 수 있도록 이미 생성된 HTML에도 패치를 적용했습니다. 가장 효과가 컸던 항목은 다음과 같습니다.

  • 이미지 크기 지정. 한 템플릿에 width="1600" height="700"이 하드코딩되어 있었지만 CSS에서는 다른 가로세로 비율을 사용하고 있었습니다. 527,815개 페이지에서 수정했습니다. width와 height는 렌더링되는 가로세로 비율과 일치해야 합니다. 그렇지 않으면 브라우저가 잘못된 크기의 공간을 미리 확보합니다 (CLS 최적화).
  • 서로 충돌하는 aspect-ratio 규칙. 두 스타일시트의 동일한 선택자에 aspect-ratio 규칙이 중복되어 있어 하나로 통합했습니다.
  • 비동기 파일에 들어 있던 중요 CSS. 첫 화면 렌더링에 필요한 모바일 규칙이 지연 로딩 스타일시트에 들어 있어 늦은 재배치가 발생했습니다. 해당 규칙을 동기식 스타일시트로 옮겼습니다.
  • 지연 로딩되는 히어로 이미지. 첫 화면 위쪽에 있는 이미지에 loading="lazy"가 적용되어 LCP가 지연되고 있었습니다. 이를 fetchpriority="high"로 교체했습니다 (LCP 최적화).
  • 너무 큰 LCP 이미지. 더 작은 이미지로 교체해 페이지당 50~440KB를 절약했습니다.
  • 인용 위젯. 첫 상호작용 시 로드되도록 변경하고 타임아웃 대체 동작을 추가했으며, 컨테이너에 480px(모바일에서는 560px)의 공간을 미리 확보했습니다. 이전에는 위젯이 삽입되면서 페이지가 이동해 CLS가 약 0.54까지 발생했습니다.
05

효과가 컸던 Cloudflare 설정

  • Email Obfuscation 비활성화. 이 기능은 로드 후 DOM을 순회하며 이메일 링크를 다시 작성하는데, 이 과정에서 레이아웃 이동이 발생했습니다. 확인한 CLS 원인 중 가장 지속적으로 나타난 항목이었습니다.
  • Rocket Loader 비활성화. 스크립트 순서를 바꾸어 지연 로딩과 충돌했습니다.
  • 배포 후 캐시 삭제. 엣지 캐시에 이전 HTML이 남아 있었으므로, 배포할 때마다 경로별로 캐시를 삭제해 오래된 페이지가 제공되지 않도록 했습니다 (Cloudflare 캐시 삭제 문서).
  • 스테이징이 아닌 운영 환경에서 측정. 동일한 Cloudflare 설정이 적용되지 않은 스테이징 환경에서는 운영 환경과 일치하지 않는 실험실 점수가 측정되었습니다.
06

스키마 및 SEO 세부 사항

  • Search Console에서 Service 엔터티에 aggregateRating과 review가 포함되어 구조화된 데이터 오류가 발생했습니다. 검증되도록 억지로 수정하는 대신 두 항목을 제거했습니다. 마크업은 사용자가 실제로 볼 수 있는 콘텐츠를 반영해야 합니다 (구조화된 데이터 가이드라인).
  • 처음에는 블로그 게시물이 지역 페이지 템플릿으로 렌더링되어 잘못된 스키마 유형을 물려받았습니다. 이제 각 템플릿이 자체 엔터티를 선언합니다.
  • 일관성이 없던 선박 및 서비스 경로 35개는 올바른 중첩 페이지로 영구 리디렉션되도록 설정했습니다 (리디렉션).
  • 미디어 경로를 /wp-content/uploads/에서 /uploads/로 변경하고 단일 301 규칙을 적용했습니다. 병렬 sed 작업으로 528,854개 파일 중 528,852개의 경로를 몇 분 만에 다시 작성했습니다.
  • Hugo가 사이트맵, 스키마, 메타 태그, robots.txt를 생성하게 된 후 Yoast를 제거했습니다.
find static-v5 -name '*.html' -print0 \
  | xargs -0 -P 8 -n 500 sed -i 's|/wp-content/uploads/|/uploads/|g'
07

절대 놓치면 안 되는 리드 수집

견적 문의 폼은 사이트의 수익을 만들어내는 핵심 기능이므로 별도의 점검 항목을 마련했습니다. 폼이 있던 모든 페이지의 빌드된 HTML에 위젯 마운트 지점이 존재해야 하고, 필드 이름은 접수 엔드포인트가 기대하는 값과 일치해야 하며, 디렉터리를 교체하는 배포 과정에서 독립적으로 운영되는 견적 문의 페이지가 삭제되어서는 안 됩니다. 리드 수집 기능이 빠진 전환은 모든 SEO 지표상으로는 성공처럼 보이지만, 실제 비즈니스에서는 문의가 사라지는 결과를 만듭니다.

08

다시 진행한다면 달리 할 일

  1. 첫 CLS 측정 전에 Email Obfuscation을 비활성화합니다.
  2. 첫날부터 빌드를 파티션으로 나눕니다.
  3. 첫날부터 content 디렉터리에 잠금을 적용합니다.
  4. 다섯 번째 수정 이후가 아니라 첫 번째 수정 전에 템플릿 수정과 전체 콘텐츠 적용 패턴을 문서화합니다.
  5. 스테이징 환경의 실험실 점수는 운영 환경을 반영하지 않으므로, 출시 체크리스트에 필드 데이터(CrUX) 점검을 포함합니다.

WordPress에 남겨둔 항목을 포함한 이 프로젝트의 비즈니스 관점은 사례 연구에서 확인할 수 있습니다.

09

출처 및 추가 자료

자주 묻는 질문

고객 사이트를 이전한 건가요?

아닙니다. Unlimited Charters는 WordPressEscape와 같은 그룹이 소유한 사내 자매 사이트입니다. 자체 테스트 사례입니다.

Hugo가 50만 페이지를 처리할 수 있나요?

가능합니다. 다만 전체 빌드에는 충분한 시간이 걸리므로 파티션 빌드와 신중한 파일 관리가 중요합니다. 실제로 발생한 문제 대부분은 Hugo의 버그라기보다 파일 시스템과 작업 프로세스에 관한 것이었습니다.

가장 심각한 레이아웃 이동의 원인은 무엇이었나요?

공간을 미리 확보하지 않은 상태에서 인용 위젯이 삽입된 것이 가장 큰 원인이었습니다. 허브 페이지에서 CLS가 약 0.54까지 발생했습니다. 로드 후 페이지를 다시 작성한 Cloudflare Email Obfuscation도 주요 원인이었습니다.

이 교훈을 소규모 사이트에도 적용할 수 있나요?

가능합니다. URL 일치성, 이미지 크기, 중요 CSS, 지연 로딩하지 않는 히어로 이미지, 지연 로딩 위젯에 관한 동일한 점검을 40페이지 규모의 사이트에도 적용할 수 있습니다. 단지 몇 시간이 아니라 몇 분 만에 끝난다는 차이가 있습니다.

내 사이트를 무료로 스캔

사이트도 같은 방식으로 개선할 수 있는지 확인해 보세요

무료 60초 진단을 통해 실제 PageSpeed 점수, 정확한 페이지 수, SEO 누락 항목, 교체가 필요한 WordPress 기능을 확인할 수 있습니다. 그런 다음 WordPressEscape가 Hugo 기반으로 사이트를 다시 구축하고, 모든 URL을 유지한 채 첫날부터 소스 코드까지 전달합니다. UC를 재구축한 것과 같은 방식입니다.

내 사이트를 무료로 스캔
계속 읽기
모든 가이드33
관련 검색어wordpress에서 hugo로 이전528,854페이지 (사내 테스트)hugo 파티션 빌드cloudflare cls 수정스키마 정리url 일치성