정적 사전 렌더링
정적 사전 렌더링은 선택적으로 활성화하는 익명 HTML 캐시입니다. 캐시 가능한 응답은 완전한 HTML 문서여야 하며 <!-- blockstudio:no-cache -->로 제외할 수 있습니다. Blockstudio은 GET이 아닌 요청, 쿼리 문자열, WordPress 관리자 화면, REST, Ajax, cron, 피드, 사이트 홈 경로의 검색 기본 경로보다 아래에 있는 검색 결과(예: /search/term/), 미리보기 및 캔버스 헤더, nonce가 포함된 요청, 선언된 동적 경로, 비밀번호/댓글 쿠키, 기본적으로 로그인된 요청을 우회합니다. 경로 아래쪽에 search 또는 preview 세그먼트만 포함된 페이지(예: /docs/blocks/preview/)는 다른 페이지와 마찬가지로 캐시됩니다.
{
"performance": {
"staticPrerender": {
"enabled": true,
"ttl": 3600,
"invalidate": "graph",
"earlyServe": true,
"serveLoggedIn": false,
"dynamicPaths": ["/account", "/checkout"],
"replayHeaders": ["Link"],
"warm": {
"enabled": true,
"interval": 900,
"concurrency": 4,
"transport": "http"
}
}
}
}
로그인한 사용자는 serveLoggedIn이 true인 경우에만 기존 캐시 적중 결과를 이용할 수 있습니다. 개인화된 응답은 캐시 항목을 생성하지 않습니다. 동적 경로는 경로 경계를 기준으로 하므로 /account은 /account/orders와 일치하지만 /accounting와는 일치하지 않습니다.
기능이 비활성화되어 있는 동안에는 파일을 쓰지 않고, 드롭인을 설치하지 않으며, 요청 또는 관리자 훅을 등록하지 않습니다. earlyServe: false도 Early Serve 관리자 콜백을 등록하지 않으며, warm.enabled: false은 cron 콜백이나 일정을 등록하지 않습니다. 두 기능 중 하나를 끄면 이전에 소유하던 상태를 한 번 제거하고, 이후 요청에서는 파일 시스템이나 cron 정리 여부를 확인하지 않습니다.
환경별로 기능 끄기
위의 모든 값은 설정 필터로도 지정할 수 있습니다. Blockstudio은 활성 테마보다 먼저 플러그인이나 테마의 Composer 오토로드에서 부팅되므로, 테마가 로드된 뒤 런타임 설정을 다시 확인하고 after_setup_theme에서 정적 사전 렌더 훅을 결정합니다. 따라서 플러그인이나 테마의 functions.php에 추가한 필터가 적용됩니다:
add_filter('blockstudio/settings/performance/staticPrerender/enabled', function ($enabled) {
return 'local' === wp_get_environment_type() ? false : $enabled;
});
이 방법으로 기능을 끄면 blockstudio.json에서 끄는 것과 동일하게 작동합니다. 요청, 콘텐츠, 관리자 또는 cron 훅이 등록되지 않으며, 이전에 조기 제공을 사용한 사이트의 Early Serve 항목은 한 번 제거됩니다. 예를 들어 init에서 나중에 추가한 필터는 등록되는 훅을 변경하지 않습니다.
서명 및 그래프 모드
signature 모드는 일반적인 익명 캐시 미스가 발생할 때 ID 키를 사용해 응답을 채웁니다. 일반 WordPress 사이트에 편리하며 사이트 수준 변경 후 갱신됩니다.
graph 모드는 결정적인 빌드/배포 통합을 위한 것입니다. 실제 소스 URL과 함께 Static_Prerender_Runtime::build_plan()을 호출하고, affectedUrls만 렌더링한 다음, 각 결과를 persist_built_response() 또는 persist_skipped_response()로 기록합니다. 계획은 공유 파일과 각 페이지의 정확한 종속성 해시를 비교합니다. 삭제된 URL과 참조되지 않는 HTML는 garbage_collect()에서 제거됩니다.
use Blockstudio\Static_Prerender_Runtime;
$plan = Static_Prerender_Runtime::build_plan($sourceUrls);
foreach ($plan['affectedUrls'] as $url) {
$result = render_with_dependencies($url);
Static_Prerender_Runtime::persist_built_response(
$url,
$result['html'],
$result['files'],
$result['virtualHashes']
);
}
$targets = array_keys($plan['live']);
Static_Prerender_Runtime::garbage_collect($targets);
선택적 대상 호스트/홈 인수는 첫 페이지 경로를 사이트 루트로 사용하지 않고 배포용 경로를 다시 작성합니다. 일괄 처리 도구는 Static_Prerender_Batch_Renderer::render()과 안정적인 N/TOTAL 샤드를 사용할 수 있습니다. Static_Prerender_Batch_Renderer::parse_shard()와 select_shard()은 샤드 옵션을 지원하므로 호출자는 렌더러가 계산할 것과 동일한 분할을 계산할 수 있습니다. 빌드 중 Static_Prerender_Batch_Renderer::is_rendering()는 현재 요청이 방문자가 아닌 일괄 렌더링인지 알려주므로 템플릿은 빌드 중 실행하면 안 되는 작업을 건너뛸 수 있습니다. 일반적인 blockstudio/static_prerender/render_internal 필터가 internal 전송 방식을 제공하며, 선택적 HTTP 대체 방식은 일반 워밍 헤더를 사용합니다.
그래프 모드에서 추적하는 항목
기본 HTTP 전송 방식을 사용하면 Static_Prerender_Batch_Renderer::render()은 각 웜 요청에 서명된 토큰을 보내고, 요청은 읽은 파일을 보고합니다. 여기에는 로드된 템플릿 WordPress, 렌더링된 모든 Blockstudio 블록의 템플릿, 템플릿 파일 및 자산 파일, blockstudio/render/dependencies을 통해 추가된 파일, 동기화된 페이지의 정의, 템플릿, 콘텐츠 및 레이아웃 파일이 포함됩니다. 이 보고서는 사이트의 캐시 디렉터리에 기록되며, 렌더러와 웹 서버는 렌더링된 HTML에 사용하는 이 디렉터리를 이미 공유합니다. 다음 빌드에서 build_plan()은 이 파일들을 다시 해시하고, 파일이 변경된 경로와 새 경로, ttl을 지난 경로, 공유 파일이 변경될 때의 모든 경로만 표시합니다(blockstudio.json, theme.json, style.css, functions.php, header.php, footer.php, inc/ 아래의 모든 항목, parts/, templates/, 그리고 Blockstudio의 번들 UI 자산 소스). 공유 서명은 컴파일된 출력물이 아닌 소스를 해시하므로, 첫 렌더링에서 빌드가 컴파일하는 _dist 파일은 서명을 바꾸지 않습니다. artifact_entry()은 렌더링 전에 build_plan()이 확인한 것과 동일한 서명에서 빌드 ID를 도출합니다.
데이터베이스에만 있는 콘텐츠는 파일이 아니므로 추적되지 않습니다. 관리자 화면에서 수정한 게시물, 옵션, 생성된 행 또는 가격이 여기에 해당합니다. 이러한 변경 사항도 반영해야 하는 빌드는 $force을 build_plan()에 전달하거나 영향을 받는 URL을 직접 렌더링해야 합니다. internal 전송 방식은 필터가 반환하는 종속성을 기록합니다.
조기 제공 및 원자적 배포
earlyServe이 활성화되면 Blockstudio은 작은 wp-content/blockstudio-static-prerender-map.php, advanced-cache.php 드롭인, 정확한 WP_CACHE 선언 하나를 관리합니다. 드롭인은 사이트별 경로 맵을 읽고, WordPress, 플러그인 또는 테마가 부팅되기 전에 조건에 맞는 캐시 적중 응답을 스트리밍합니다.
Blockstudio은 다른 소유자가 만든 맵, 드롭인 또는 WP_CACHE 선언을 덮어쓰지 않습니다. 그래프 아티팩트를 통해 맵을 교체하기 전에 참조된 모든 HTML 파일을 검증합니다. 검증에 실패하면 이전 그래프가 계속 활성 상태로 유지됩니다. 멀티사이트 항목은 맵을 공유하지만 호스트, 홈 경로 및 사이트 ID별로 격리됩니다. 기능을 비활성화하거나 Blockstudio을 비활성화하면 현재 사이트의 항목만 제거하며, 마지막으로 소유한 항목이 사라진 뒤에만 공유 아티팩트를 제거합니다.
배포 도구는 완전히 렌더링된 그래프를 원자적으로 활성화할 수 있습니다:
$entry = Static_Prerender_Runtime::artifact_entry($targetUrls);
Blockstudio\Static_Prerender_Early_Serve::install_artifact_entry(
$entry,
Static_Prerender_Runtime::cache_root_path()
);
구성이 최우선 기준으로 유지됩니다. install_artifact_entry()은 false을 반환합니다. enabled와 earlyServe이 모두 true인 경우에만 예외가 적용되므로, 배포로 설치한 맵, 드롭인 및 WP_CACHE 선언이 다음 관리자 요청에서 제거되는 일은 없습니다.
install_artifact_entry()은 항목의 build_id을 유지하므로 배포 후 installed_map_entries()가 반환하는 항목과 비교할 수 있습니다. 맵은 PHP 파일이며 include로 읽습니다. 쓸 때마다 맵이 opcode 캐시에서 제거되므로 opcache.enable_cli가 활성화된 경우에도 같은 프로세스에서 새 항목을 읽을 수 있습니다.
아티팩트를 설치하면 문서가 전용 아티팩트 범위로 이동하며, 이 범위는 보존 정리의 대상이 되지 않습니다. 맵이 참조하는 파일은 위치와 관계없이 삭제되지 않으므로 실시간 렌더링 트래픽이 조기 제공 경로의 보존 기간을 만료시키지 않습니다. 경로 키는 완전한 콘텐츠 주소 지정 방식이 아니므로 다시 렌더링해도 키가 바뀌지 않을 수 있습니다. 설치 시 바이트를 비교해 내용이 다른 아티팩트 문서를 원자적으로 교체하고, 동일한 문서는 그대로 두며, 저장소 사본이 사라진 아티팩트 문서는 유지합니다. Static_Prerender_Early_Serve::last_promotion()은 마지막 설치에서 승격, 교체, 건너뜀 또는 유지된 경로 수를 보고하므로 배포 로그에 기록할 수 있습니다.
저장된 문서는 URL으로 연결하는 빌드 자산을 고정하며, 해당 파일은 자체 보존 기간을 적용받으므로 문서와 자산 중 하나가 다른 하나보다 오래 남을 수 있습니다. 제공하기 전에 PHP 캐시와 드롭인은 연결된 콘텐츠 해시 Tailwind 스타일시트가 디스크에 있는지 확인합니다. 스타일시트가 사라진 문서는 스타일이 없는 상태로 제공하는 대신 WordPress로 전달되어 스타일시트와 문서가 함께 다시 게시됩니다. 응답을 저장하기 전에도 같은 확인을 수행하므로 제공할 수 없는 문서는 기록되지 않습니다.
Accept 헤더에 text/markdown이 포함된 요청은 PHP 저장소와 드롭인을 모두 우회합니다. 저장된 문서는 HTML이므로 페이지는 해당 요청에 소스 Markdown로 응답할 수 있습니다.
따라서 제공된 문서는 Vary: Accept을 전송합니다. Blockstudio을 업데이트하면 다음 맵 쓰기 시 이전 드롭인이 다시 작성됩니다.
맵에 있는 그래프 경로는 항상 활성화된 아티팩트를 사용합니다. 안전한 익명 경로가 해당 맵에는 없지만 WordPress이 이후에 이를 렌더링하고 저장했다면 Early Serve는 WordPress을 부팅하기 전에 ID 키 기반 런타임 저장소를 대체 경로로 사용합니다. 이 기능은 의도적으로 범위를 제한한 배포 그래프에 포함되지 않은 생성 경로나 롱테일 경로를 지원합니다. 대체 경로는 활성 그래프 ID와 함께 맵 경로와 동일한 호스트, 경로 정규화, TTL, 쿠키, 헤더, 쿼리 문자열, 동적 경로 및 피드 우회 규칙을 사용합니다. 또한 런타임 저장소에 저장된 문서만 찾으며, 여기에 검색 결과는 포함되지 않습니다.
응답 헤더
저장된 문서는 이를 렌더링한 요청 없이 재생되므로, 테마나 플러그인이 header()와 함께 보내는 헤더는 모든 응답에서 누락됩니다. Blockstudio는 각 문서에 replayHeaders에 지정된 헤더를 저장하고, PHP 캐시와 조기 제공 드롭인 양쪽에서 다시 전송합니다. 기본값인 ["Link"]에는 Markdown 대체 링크(rel="alternate"; type="text/markdown"), rel="describedby" 또는 rel="canonical" 같은 헤더가 포함됩니다. 이름은 대소문자를 구분하지 않고 일치하며, 설정 필터는 다른 값과 마찬가지로 목록을 변경합니다:
add_filter('blockstudio/settings/performance/staticPrerender/replayHeaders', function (array $headers): array {
$headers[] = 'X-Robots-Tag';
return $headers;
});
헤더 재생을 사용 중지하려면 replayHeaders을 []로 설정합니다. 명시적 목록은 기본 목록을 대체하므로, 다른 헤더 이름을 추가하면서 링크 헤더도 재생하려면 Link를 포함하세요.
헤더는 페이지를 렌더링하는 프로세스에서 캡처됩니다. 실시간 캐시 미스가 저장될 때는 headers_list()에서, 빌드나 워머가 HTTP 위에서 렌더링할 때는 워밍 요청 자체에서 캡처됩니다. 따라서 웹 서버가 자체적으로 추가하고 제공되는 모든 문서에 다시 추가하는 헤더는 저장되지 않습니다. HTTP 렌더링에서 보고서가 작성되지 않은 경우에만 해당 응답의 헤더를 사용합니다. internal 전송 계층은 결과에 이를 headers로 반환하며, persist_built_response()는 마지막 인수로 이를 받습니다. 이 인수는 Name: value 줄 또는 이름과 값의 맵 형식일 수 있습니다.
헤더는 문서 옆의 <key>.headers.json에 기록되고, 아티팩트 승격, 가비지 컬렉션, 보존 기간 정리 과정에서도 문서와 함께 이동하며, 다시 렌더링할 때 헤더를 보내지 않으면 제거됩니다. 목록에 있더라도 쿠키, 캐시, 전송 헤더는 저장하거나 재생하지 않습니다: Set-Cookie, Cache-Control, Expires, Pragma, Age, ETag, Last-Modified, Vary, Content-Type, Content-Length, Content-Encoding, Transfer-Encoding, Location, Status, Date, 그리고 홉 간 및 인증 헤더입니다. 제공되는 문서는 자체 Content-Type 및 Vary을 설정합니다.
저장된 헤더는 전송 시 목록과 다시 대조됩니다. PHP 캐시는 현재 설정을 읽고, 드롭인은 사이트 맵 항목에 저장된 복사본을 읽습니다. 이 복사본은 다음 아티팩트 설치나 맵 동기화 때 갱신됩니다. 업그레이드 전에 저장된 문서에는 헤더 파일이 없으며, 다시 렌더링될 때까지 이전과 동일하게 제공됩니다.
워밍, 유지 관리 및 관측 가능성
웜 큐는 영구적으로 유지되고, URL 병합을 지원하며, 단일 실행으로 처리되고, 시간 초과된 클레임을 복구합니다. 콘텐츠와 사이트가 변경되면 현재 서명이 같더라도 작업을 새로 등록하고, 주기 실행은 오래된 작업만 등록합니다. 예약되었거나 wp bs prerender warm를 통해 실행되는 각 패스는 최대 warm.concurrency개의 작업을 렌더링합니다. graph 모드에서는 그래프 아티팩트가 하나의 단위로 빌드되고 활성화되므로, 개별 URL 워머가 꺼집니다.
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
wp bs prerender map status
wp bs prerender map prune --dry-run
status은 활성 ID, 파일, 바이트, 그래프 레코드, 대기열 상태, 조기 제공 맵 보고서, 범위별 적중/누락/빌드/실패 횟수를 보고합니다.
조기 제공 맵은 한 설치에 속한 모든 사이트가 공유합니다. map status(및 Static_Prerender_Early_Serve::map_report())은 조기 제공에 더 이상 사용할 수 없는 항목을 나열합니다. 여기에는 더 이상 존재하지 않는 사이트의 orphaned 항목과 디렉터리가 사라진 dead 항목이 포함되며, 남아 있는 항목의 missing 경로 문서 수도 표시합니다. map prune(Static_Prerender_Early_Serve::prune_map())은 맵 잠금 상태에서 고립되었거나 만료된 항목을 제거하고 각 항목의 사유를 보고합니다. --dry-run은 보고만 합니다. 마지막 항목이 제거되면 맵, 드롭인 및 WP_CACHE 선언도 제거됩니다. 멀티사이트 네트워크에서 사이트를 삭제하면 해당 항목이 즉시 제거됩니다. 캐시 정리는 활성화된 아티팩트가 제공되는 네임스페이스를 수집하지 않으므로 파일이 다른 방법으로 제거된 경우에만 항목이 만료됩니다.
개별 응답 결과는 blockstudio/static_prerender/outcome으로, 공유 캐시의 모든 결과는 blockstudio/cache/outcome로 확인하세요.
제거
Composer 번들 설정과 같이 플러그인 비활성화 훅이 없는 설치 환경에서는 다음 명령 하나로 기능이 소유한 모든 항목을 제거할 수 있습니다:
wp bs teardown
설치 환경이 소유한 cron 이벤트와 정적 사전 렌더 상태를 제거합니다. 여기에는 현재 사이트의 맵 항목과, 마지막으로 소유한 항목이 사라졌을 때의 공유 드롭인 및 WP_CACHE 선언이 포함됩니다. 구성 파일은 그대로 두므로 기능을 다시 활성화해도 깔끔하게 시작됩니다.
프로덕션 환경에 도입하기
권장 도입 순서:
performance.profile을speed로 설정한 다음, head 출력, 피드, oEmbed 또는 XML-RPC에 의존하는 플러그인을 확인합니다.assets/media.json를 생성하고 템플릿을bs_media_image()로 옮긴 다음performance.media.lazy을 활성화합니다.earlyServe을 끈 상태로performance.staticPrerender을 활성화하고wp bs prerender status로 캐시 적중을 확인한 다음earlyServe을 활성화합니다.
기능별로 롤백할 수 있습니다. staticPrerender.enabled을 false로 설정하면 Blockstudio이 소유한 Early Serve 상태와 워밍 일정을 한 번 제거한 뒤 사전 렌더 런타임을 등록하지 않습니다. performance.profile을 다시 compat로 설정하면 프로파일이 취소됩니다. 각 설정은 다른 계층을 그대로 둡니다.
프로파일, 프로파일러와 그 기반이 되는 렌더링 기법입니다.
생성된 모든 아티팩트가 저장되는 단일 캐시 디렉터리입니다.