WordPress을 정적 HTML으로 제공하기
마케팅 사이트나 문서 사이트의 대부분 페이지는 익명 방문자마다 똑같습니다. WordPress은 요청이 들어올 때마다 부팅되고, 모든 플러그인을 불러오고, 테마를 실행하고, 블록을 렌더링합니다. 페이지 캐시 플러그인이 도움이 될 수 있지만, 안전한 저장 방식에 대한 자체 규칙을 가진 구성 요소가 하나 더 늘어납니다.
Blockstudio에는 선택적으로 사용할 수 있는 정적 사전 렌더링 기능이 포함되어 있습니다. 완성된 익명 HTML 문서를 전용 캐시 디렉터리에 저장하고, 허용하면 advanced-cache.php 드롭인에서 제공해 WordPress이 부팅되기 전에 응답할 수 있습니다. 모든 설정은 blockstudio.json에서 관리합니다.
이 가이드에서는 기능을 단계별로 켜는 방법, 캐시되는 항목을 확인하는 방법, 로그인한 방문자를 안전하게 보호하는 규칙 하나를 설명합니다. 마지막으로 오리진이 캐시 가능하다고 표시한 항목만 캐시하는 CDN 설정을 소개합니다.
요청 처리 방식
사전 렌더링을 켜면 처리 대상 요청은 다음 세 가지 방식 중 하나로 끝납니다:
- 조기 응답 적중. 드롭인이 경로 맵에서 저장된 문서를 찾아 WordPress이 로드되기 전에 스트리밍합니다. 응답에는
X-Blockstudio-Static-Prerender: HIT-EARLY이 포함됩니다. - 적중. WordPress이 부팅되고
template_redirect에서 Blockstudio가 최신 저장 문서를 찾아 템플릿을 렌더링하는 대신 전송합니다. 응답에는X-Blockstudio-Static-Prerender: HIT가 포함됩니다. - 캐시 미스. WordPress이 페이지를 정상적으로 렌더링합니다. 방문자가 익명이고 결과가 상태 코드 200인 완전한 HTML 문서라면 Blockstudio이 다음 요청을 위해 저장합니다.
처리 대상이 아닌 요청은 캐시에 전혀 접근하지 않습니다.
1단계: 프로필과 캐시 켜기
성능 프로필과 사전 렌더링을 켜되, 조기 제공은 끈 상태로 시작하세요:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"performance": {
"profile": "speed",
"staticPrerender": {
"enabled": true,
"ttl": 86400,
"earlyServe": false,
"dynamicPaths": ["/account", "/checkout", "/login"],
"warm": {
"enabled": true,
"interval": 900,
"concurrency": 4
}
}
}
}
각 설정의 기능:
profile: "speed"은 프로덕션 프런트엔드 기본값을 적용합니다. 헤드의 불필요한 요소, oEmbed 검색, XML-RPC 및 일반 코어 프런트엔드 에셋을 제거하고, 사용자가 의도한 경우 동일 출처 링크를 미리 가져옵니다. 코어 프런트엔드 에셋에 의존하는 페이지는 눈에 띄게 깨질 수 있으므로 이 설정을 먼저 테스트하세요. 하위 설정은 프로필 값을 덮어씁니다.staticPrerender.enabled은 런타임을 등록합니다.false인 동안에는 파일을 쓰지 않고 요청 훅도 등록하지 않습니다.ttl는 저장된 문서의 최대 수명(초)이며 기본값은86400입니다.dynamicPaths에는 항상 실시간으로 렌더링해야 하는 경로 접두사가 나열됩니다.warm은 오래된 공개 URL을interval초마다 다시 렌더링하는 백그라운드 워머를 예약합니다.
$schema 줄은 모든 키를 다루므로, JSON 스키마를 지원하는 편집기는 최소값이 1인 "ttl": 0 같은 오류를 표시합니다.
2단계: 처리 대상 확인하기
Blockstudio은 저장 대상을 보수적으로 판단합니다. 다음 요청은 항상 캐시를 우회합니다:
GET이외의 요청- 쿼리 문자열이 있는 URL 요청
wp-admin,wp-json,wp-login.php,xmlrpc.php, Ajax 및 cron 요청- 피드, 검색 및 미리보기 경로
X-WP-Nonce헤더를 보내는 요청dynamicPaths아래의 경로wordpress_logged_in_*,wp-postpass_*또는comment_author_email_*쿠키가 있는 방문자. 단,serveLoggedIn가 켜져 있으면 제외
동적 경로는 경로 경계를 기준으로 일치합니다. 위 설정을 적용하면 다음과 같습니다:
| 요청 | 우회 여부 |
|---|---|
/pricing/ |
아니요 |
/account/orders/ |
예 |
/accounting/ |
아니요 |
/checkout |
예 |
/pricing/?utm_source=x |
예 |
/blog/feed/ |
예 |
저장할 때는 완전한 문서만 보관합니다. 응답은 <!doctype html 또는 <html로 시작해야 하고 상태 코드는 200여야 하며, 옵트아웃 마커가 없어야 합니다. 저장되지 않아야 하는 템플릿은 페이지 어디에나 마커를 출력할 수 있습니다:
<!-- blockstudio:no-cache -->
오류 페이지는 절대 저장되지 않으므로, 테마를 적용한 404도 성공 응답으로 재생될 수 없습니다.
3단계: 적중 확인하기
시크릿 창에서 페이지 몇 개를 방문한 다음 Blockstudio에 저장된 항목을 확인하세요:
wp bs prerender status
{
"enabled": true,
"invalidate": "signature",
"identity": "e6cdd3fcda14ad6ded85a763bd01a33b",
"cacheRoot": ".../wp-content/blockstudio/cache/sites/.../static-prerender",
"files": 0,
"bytes": 0,
"records": 0,
"queue": {
"pending": 0,
"processing": 0,
"done": 0,
"unique": 0,
"bytes": 0
},
...
"diagnostics": []
}
문서가 저장되면 files과 bytes의 크기가 늘고, queue에는 워머의 대기 작업이 표시되며, diagnostics에는 범위별 적중, 미스, 빌드 및 실패 횟수가 기록됩니다. 페이지 하나를 확인하려면 익명 방문자로 두 번 요청한 뒤 다음 헤더를 찾으세요:
curl -s -o /dev/null -D - https://example.com/pricing/ | grep -i x-blockstudio-static-prerender
두 번째 응답에는 X-Blockstudio-Static-Prerender: HIT이 포함됩니다. 위와 같이 GET을 사용하세요. curl -I는 HEAD 요청을 보내며, 이 요청은 항상 캐시를 우회합니다.
4단계: WordPress이 부팅되기 전에 제공하기
적중이 올바르게 작동하면 "earlyServe": true을 설정하세요. 그러면 Blockstudio이 세 가지 작은 상태 항목을 관리합니다. wp-content/advanced-cache.php 드롭인, 공유 wp-content/blockstudio-static-prerender-map.php 경로 맵, wp-config.php의 WP_CACHE 선언입니다. 이 항목들은 다음 관리자 요청에서 설치됩니다.
공유 호스팅 및 멀티사이트 환경에서 안전하게 사용하려면 몇 가지 규칙을 따라야 합니다:
- Blockstudio은 자신이 관리하지 않는 드롭인, 맵 또는
WP_CACHE줄을 덮어쓰지 않습니다. 다른 캐싱 플러그인이 이미advanced-cache.php를 관리하고 있으면 조기 제공은 비활성화된 상태로 유지됩니다. WP_CACHE가 이미true로 정의되어 있으면wp-config.php는 그대로 둡니다.wp-config.php에 쓰기 권한이 없는 호스트에서는 직접 정의하세요.- 제공 전에 드롭인과 PHP 경로 모두 문서가 링크하는 콘텐츠 해시 Tailwind 스타일시트가 여전히 있는지 확인합니다. 없으면 스타일이 적용되지 않은 상태로 제공하는 대신 요청을 WordPress로 전달합니다.
- 멀티사이트 항목은 하나의 맵을 공유하지만 호스트, 홈 경로, 사이트 ID별로 분리됩니다.
Link에 지정된 응답 헤더는 기본적으로replayHeaders에 포함되며, 각 문서와 함께 저장되고 모든 요청에 다시 전송됩니다. 따라서 페이지가header()와 함께 보내는Link헤더는 조기 제공에서도 유지됩니다. 쿠키 및 캐시 헤더는 재생하지 않습니다.
조기 적중에는 X-Blockstudio-Static-Prerender: HIT-EARLY이 포함됩니다. earlyServe 또는 enabled를 끄면 Blockstudio이 소유한 상태가 한 번 제거되고, wp bs teardown는 비활성화 훅이 없는 Composer 설치에서 해당 상태를 명시적으로 제거합니다.
로그인한 방문자와 동일한 마크업
기본적으로 로그인한 방문자에게는 항상 실시간 렌더링을 제공합니다. "serveLoggedIn": true을 설정하면 기존에 저장된 문서도 사용할 수 있어 편집자와 고객도 익명 방문자만큼 빠르게 사이트를 이용할 수 있습니다.
개인화된 응답은 캐시 항목을 만들지 않습니다. 로그인한 사용자가 캐시 적중에 실패하면 실시간 렌더링을 수행하고 저장하지 않습니다. 이로 인해 생기는 결과는 간과하기 쉽습니다. serveLoggedIn을 켜면 로그인한 방문자는 익명 방문자용 문서가 있을 때 이를 받고, 문서가 없을 때만 개인화된 실시간 렌더링을 받습니다. 현재 사용자를 기준으로 하는 템플릿 분기는 캐시 적중이 아닐 때만 나타나므로 같은 페이지가 방문할 때마다 달라지고, 캐시된 경로에서는 개인화 분기가 사실상 작동하지 않습니다.
따라서 dynamicPaths 밖의 모든 경로에서 로그인 사용자용 마크업은 익명 사용자용 마크업과 바이트 단위로 동일해야 합니다. 즉, 정적 경로에서 렌더링되는 템플릿에는 is_user_logged_in() 또는 wp_get_current_user() 분기가 없어야 합니다.
<?php // Do not do this on a static route. ?>
<?php if ( is_user_logged_in() ) : ?>
<a href="/account/">Hi, <?php echo esc_html( wp_get_current_user()->display_name ); ?></a>
<?php else : ?>
<a href="/login/">Sign in</a>
<?php endif; ?>
해결 방법은 두 가지입니다. 계정 대시보드처럼 페이지 전체가 개인화된 경우 경로를 dynamicPaths 안으로 옮기세요. 또는 페이지를 정적으로 유지하고 개인화된 부분을 동적 블록 아일랜드로 렌더링하세요. 이 방식은 저장된 HTML에 캐시 안전한 플레이스홀더를 제공하고 방문자 자신의 요청에서 실제 조각을 가져옵니다.
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
캐시된 페이지의 개인화 조각 가이드에서 해당 블록을 만드는 방법을 설명합니다.
서명 또는 그래프 무효화
invalidate은 저장된 문서의 만료 방식을 결정합니다.
| 항목 | signature (기본값) |
graph |
|---|---|---|
| 캐시를 채우는 주체 | 익명 방문자의 캐시 미스와 워머 | 빌드 단계와 익명 방문자의 캐시 미스 |
| 항목 만료 조건 | TTL, 글 저장, 사이트 수준 변경 | 새 빌드, TTL은 최대 한도 |
| 백그라운드 워머 | 사용 가능 | 꺼짐 |
| 적합한 사이트 | 일반 사이트 | 배포 파이프라인이 있는 사이트 |
signature 모드는 별도 도구가 필요 없습니다. 글을 저장하면 홈페이지와 해당 글의 고유주소를 삭제하거나 다시 워밍하고, 테마 전환과 같은 사이트 수준 변경이 캐시 ID를 변경합니다.
graph 모드는 예측 가능한 배포를 위한 것입니다. 빌드는 Static_Prerender_Runtime::build_plan()을 사용해 계획을 계산하고, 영향을 받는 URL만 렌더링한 다음 각 결과를 기록합니다. 완성된 세트는 Static_Prerender_Early_Serve::install_artifact_entry()로 원자적으로 활성화됩니다. 참조된 문서 중 하나라도 검증에 실패하면 이전 세트가 계속 활성 상태로 유지됩니다. 매핑된 경로는 다음 빌드가 대체할 때까지 활성화된 아티팩트에서 제공되므로 wp-admin에서 편집한 콘텐츠는 다음 배포 때 해당 경로에 반영됩니다. 아티팩트는 하나의 단위로 빌드되고 활성화되므로 이 모드에서는 사이트별 URL 워머가 꺼집니다. 일반적인 프로덕션 구성은 다음과 같습니다.
{
"performance": {
"profile": "speed",
"staticPrerender": {
"enabled": true,
"invalidate": "graph",
"ttl": 2592000,
"earlyServe": true,
"serveLoggedIn": true,
"dynamicPaths": [
"/account",
"/cart",
"/checkout",
"/login",
"/reset-password"
]
}
}
}
30일 ttl은 제공되는 문서의 최대 경과 기간만 제한합니다. 최신 상태는 그래프를 다시 빌드하는 배포에서 비롯됩니다. 빌드 API, 샤딩, 내부 렌더링 전송은 정적 사전 렌더링 참조에서 다룹니다.
앞단에 CDN 배치하기
사전 렌더링은 공유해도 안전한 응답을 알려줍니다. HIT 헤더가 있는 응답만 해당합니다. 오리진에서 이를 캐시 헤더로 변환하고 CDN이 오리진을 따르게 하세요. PHP-FPM 앞단에 nginx를 둘 경우:
map $upstream_http_x_blockstudio_static_prerender $edge_cache_control {
"~^HIT" "public, s-maxage=604800";
default "";
}
server {
listen 80;
server_name example.com;
root /var/www/html;
index index.php;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass unix:/run/php/php-fpm.sock;
add_header Cache-Control $edge_cache_control;
}
}
정규식은 HIT과 HIT-EARLY 모두와 일치합니다. 다른 모든 응답에서는 변수가 비어 있고 nginx는 값이 빈 헤더를 추가하지 않으므로 캐시 미스, 동적 경로, 로그인 사용자 렌더링에는 오리진의 공유 캐시 수명이 적용되지 않습니다.
CDN 측에서는 다음과 같이 설정합니다.
- 오리진이 캐시 수명을 보낼 때만 HTML을 캐시합니다. 수명이 없는 응답에는 기본 엣지 TTL을 비활성화합니다.
- Blockstudio이 개인 정보로 취급하는 쿠키(
wordpress_logged_in_,wp-postpass_,comment_author_email_)와 자체dynamicPaths,wp-admin,wp-json에 대해서는 엣지를 우회합니다. - 페이지, 템플릿 또는 에셋이 변경되는 배포마다 CDN을 비웁니다. 오리진 캐시는 자동으로 교체되지만 엣지는 이를 알지 못합니다.
Tailwind을 "output": "link"과 함께 사용하면 스타일시트 URL에 콘텐츠 해시가 적용되므로 해당 경로에 장기 불변 캐시 헤더를 설정할 수 있습니다.
유지 관리 명령
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
wp bs teardown
warm은 오래된 공개 URL을 대기열에 추가하고 실행당 최대 warm.concurrency개까지 렌더링한 뒤 JSON 요약을 출력합니다. purge은 현재 사이트의 저장된 문서와 대기열을 삭제합니다. teardown는 cron 이벤트와 이 설치가 소유한 조기 제공 상태를 제거하며 설정 파일은 그대로 둡니다.
다음 순서로 배포하세요. 먼저 프로파일링을 수행하고, earlyServe을 끈 상태로 사전 렌더링을 적용한 다음 status과 헤더가 올바른지 확인한 뒤 조기 제공을 시작합니다. 각 계층은 해당 값을 원래대로 설정해 개별적으로 롤백할 수 있습니다.
다음 단계
- 정적 사전 렌더링 참조: 그래프 빌드, 아티팩트 활성화, 보존, 관측성 훅.
- 성능:
speed프로파일이 변경하는 내용과 측정 방법. - 캐싱: 저장된 모든 문서가 있는 캐시 디렉터리.
- 캐시된 페이지의 개인화 조각: 정적 경로의 방문자별 콘텐츠.
- Blockstudio 사이트 배포: 페이지 동기화, 캐시 비우기, 워밍이 릴리스에 들어가는 위치.