본문으로 건너뛰기

Dennis · 2026년 10월 14일

Blockstudio 7.7

Blockstudio 7.7에서는 WordPress 게시물이 없는 문서를 위한 가상 경로를 추가하고, 대상별 사전 렌더링 빌드를 개선하며, 기존 블록을 더 안정적으로 편집하고 렌더링할 수 있습니다. 또한 PHPStan의 블록 태그 검사를 확장하고 번들로 제공되는 UI 구성 요소 전반의 접근성을 개선합니다.

파일 우선 워크플로우는 그대로 유지됩니다. 블록은 템플릿에서 렌더링되며, 파일 기반 페이지는 명시적인 CLI 또는 API 동기화를 통해 변경됩니다. 이번 릴리스에서는 방문자 또는 관리자 요청 시 페이지가 자동으로 동기화되지 않습니다.

간단히 요약하면:

  • 가상 경로: 게시물을 만들거나 사용자 지정 리디렉션 처리기를 작성하지 않고도 구성 요소 갤러리, 카탈로그 또는 다른 완전한 문서를 제공할 수 있습니다.
  • 대상별 사전 렌더링 빌드: HTTP 빌드는 각 페이지가 사용하는 소스 파일을 기록하므로 다음 빌드에서 영향을 받은 경로만 렌더링할 수 있습니다.
  • 캐시 보존: 캐시된 페이지에서 사용 중단된 스타일시트를 계속 사용할 수 있도록 하고, 사용하지 않는 조기 제공 맵 항목을 확인하거나 정리할 수 있습니다.
  • 편집기 안정성: 여러 블록을 선택해도 각 블록의 값이 유지됩니다. RichText와 사이드바 필드에서 실행 취소와 다시 실행이 작동하고, 상속된 컨텍스트가 올바른 블록에 유지됩니다.
  • 파일 콘텐츠 충실도: 중첩 목록, 섹션 요소, 인라인 HTML, 단축 코드, 이스케이프된 속성이 파싱과 렌더링 후에도 유지됩니다.
  • PHPStan 개선 사항: 접두사 태그, 별칭, 매핑된 페이지 요소, 템플릿 변수를 프로젝트 자체 정의와 대조해 검사합니다.
  • 접근성 있는 UI: 컨트롤 상태가 올바르게 표시되고, 레이블을 눌러 적절한 입력을 전환할 수 있으며, 목록 및 표 구성 요소가 유효한 HTML 구조를 사용합니다.
  • 번역: 설치된 JavaScript 번역을 편집기와 관리자 개요에서 불러옵니다. 이전에 번역되지 않았던 필드 컨트롤도 포함됩니다.

가상 경로

일부 페이지는 편집기에서 관리하는 게시물이 아니라 데이터에서 만들어집니다. 예를 들어 구성 요소 참조 페이지에는 자체 URL와 문서 제목이 필요할 수 있지만 wp_posts에 항목을 만들 필요는 없습니다.

Blockstudio\Virtual_Routes으로 문서를 등록합니다:

PHP
add_action('init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function () {
            get_header();
            echo bs_block([
                'name' => 'mytheme/card',
                'data' => ['heading' => 'Example card'],
            ]);
            get_footer();
        },
        ['title' => 'Component gallery']
    );
});

이 경로는 /components/을 제공합니다. 콜백은 Blockstudio의 출력 버퍼 안에서 실행되므로 렌더링된 블록의 스타일, 스크립트, 번들 UI 에셋, Tailwind 출력을 일반 파이프라인을 통해 처리합니다. WordPress는 일치하는 경로를 404로 바꾸거나 게시물로 리디렉션하지 않습니다.

여러 URL을 처리하려면 prefix을 true로 설정하고 match 콜백을 제공합니다. 콜백은 경로 아래의 경로 문자열을 받아 렌더러에 필요한 값을 반환합니다. null 또는 false를 반환하면 요청은 WordPress에 맡겨집니다. 정적 사전 렌더링 빌드에 포함할 경로를 나열하려면 urls을 사용합니다. 단일 비접두사 경로는 기본적으로 해당 경로 자체를 포함합니다.

Virtual_Routes::urls()은 사이트맵을 구성하는 통합 기능에 절대 URL을 반환합니다. 가상 문서를 WordPress의 게시물 사이트맵에 자동으로 추가하지는 않습니다.

전체 API 및 옵션은 가상 경로를 참조하세요.

더 정밀한 사전 렌더링 빌드

HTTP을 대상으로 실행된 그래프 모드 빌드는 이제 각 경로에서 사용한 파일을 기록합니다. 여기에는 WordPress 템플릿, 렌더링된 블록 템플릿과 에셋, 파일 페이지 정의와 레이아웃, blockstudio/render/dependencies을 통해 추가한 종속 항목이 포함됩니다.

다음 빌드에서 build_plan()은 해당 종속 항목을 비교합니다. 블록 템플릿이 변경되면 이에 종속된 경로만 렌더링 대상으로 표시되므로 관련 없는 모든 페이지를 다시 빌드할 필요가 없습니다. 공유 구성이 변경되면 여전히 전체 빌드에 영향을 주며, 새 경로와 만료된 경로는 이전과 같이 렌더링됩니다.

데이터베이스만 변경된 내용은 파일 종속 항목으로 간주되지 않습니다. 옵션, 게시물 또는 다른 데이터베이스 값을 반영해야 하는 배포에서는 빌드를 강제로 실행하거나 영향을 받는 URL을 명시적으로 렌더링해야 합니다.

이번 릴리스에서는 첫 렌더링 도중 빌드 식별자가 바뀌는 문제, 오래된 opcode 캐시 조기 제공 맵, 경로에 search 또는 preview가 포함됐다는 이유만으로 유효한 URL이 제외되는 문제도 해결했습니다. Markdown 요청은 Accept: text/markdown을 사용해 캐시된 HTML을 우회하며, 관련 응답에는 Vary: Accept가 포함됩니다.

정적 사전 렌더링은 이제 활성 테마에서 등록한 필터를 고려해 후크 연결 여부를 결정합니다. 따라서 이전의 설정 조회로 기능이 활성 상태에 남지 않으므로 테마에서 기능을 비활성화할 수 있습니다.

정적 사전 렌더링을 참조하세요.

캐시 보존 및 관리

캐시된 HTML 페이지는 스타일시트를 컴파일한 런타임 식별자가 만료된 뒤에도 계속 제공될 수 있습니다. cache.namespaceGrace은 정리 과정에서 사용 중단이 처음 확인된 시점부터 이전 네임스페이스를 사용할 수 있는 기간을 제어합니다:

JSON
{
  "cache": {
    "namespaceGrace": 777600
  }
}

이 예시에서는 사용 중단된 파일을 9일 동안 보존합니다. 기본값은 1일입니다. 현재 활성 상태인 네임스페이스와 배포된 사전 렌더링 아티팩트를 제공하는 네임스페이스는 정리 대상에서 보호됩니다.

조기 제공 맵을 확인하고 정리하는 명령도 있습니다:

셸
wp bs prerender map status
wp bs prerender map prune --dry-run
wp bs prerender map prune

삭제된 사이트나 없는 디렉터리의 항목을 보고하고 제거합니다. 멀티사이트 사이트를 삭제하면 해당 항목도 제거됩니다. 누락된 경로 문서는 별도로 보고하므로 유효한 사이트 항목 전체가 제거되지는 않습니다.

보존 지침은 캐싱을, 명령은 맵 관리를 참조하세요.

더 안정적인 편집기

이제 여러 블록을 선택한 상태에서 블록을 편집하면 해당 블록만 업데이트됩니다. 저장할 때 선택한 블록 사이에 속성을 복사하지 않고 각 블록의 자체 콘텐츠, 키, 메타데이터, 잠금 상태를 유지합니다.

RichText 값은 블록 속성에 직접 저장되므로 Gutenberg에서 실행 취소와 다시 실행에 포함할 수 있습니다. 사이드바 필드도 동일한 기록에 포함됩니다. InnerBlocks templateLock="false"은 실제 불리언 값으로 전달되므로 바깥 영역이 잠겨 있어도 콘텐츠 잠금을 해제할 수 있습니다.

초기 사전 로드에 편집 중인 게시물의 ID와 유형을 전달하므로 첫 렌더링부터 템플릿에서 올바른 메타데이터를 읽을 수 있습니다. 서로 다른 부모 아래에 있는 동일한 자식 블록은 사전 로드와 렌더링 캐시에서 상속된 컨텍스트를 각각 유지합니다. 초기 요청 중 속성이나 컨텍스트가 변경되어도 미리보기가 이전 상태로 남지 않습니다.

Blockstudio은 블록 루트 사이에 숨겨진 렌더링 표시 요소를 삽입하지 않습니다. 이제 .card + .card 같은 인접 형제 선택자는 프런트엔드와 동일한 요소 관계를 편집기에서도 인식하며, 편집기 미리보기와 삽입기 미리보기 렌더링은 서로 분리된 상태로 유지됩니다.

사이트 전체 옵션의 안전한 저장

옵션 기반 필드는 여전히 사이트 전체에서 사용하는 값을 제공하지만, 게시물을 저장해도 저장된 필드 사본을 모두 무조건 기록하지 않습니다:

  • 임시 글, 검토 대기, 비공개 및 예약 저장에서는 사이트의 실시간 옵션을 기록하지 않습니다.
  • 공개된 게시물을 저장할 때는 해당 편집에서 변경된 제공 필드를 기록합니다.
  • 제목만 변경해 저장하면 기존 사본이 최신 사이트 전체 값을 되돌리지 않습니다.
  • 필드가 없거나 블록을 삭제해도 기존 옵션이 삭제되지 않습니다.
  • 명시적인 null은 옵션을 삭제합니다. 빈 문자열, false, 0, 빈 배열은 유효한 값으로 유지됩니다.

업그레이드할 때 확인해야 할 주요 동작 변경 사항입니다. 통합 기능에서 비공개 또는 임시 게시물을 사용해 실시간 옵션을 업데이트했다면 해당 옵션을 명시적으로 쓰거나 공개된 구성 게시물을 사용하세요. 게시물 메타데이터 저장에는 공개 게시물만 허용하는 제한이 적용되지 않습니다.

전체 저장 규칙은 저장을 참조하세요.

파일 콘텐츠 보존

HTML에서 블록으로 변환하는 파이프라인은 작성한 구조를 더 많이 보존합니다:

  • 중첩 목록은 상위 항목의 내부 목록 블록이 됩니다. 목록과 항목의 클래스는 보존되며 일반적인 평면 목록은 이전과 같은 출력이 유지됩니다.
  • main, header, footer, article, aside는 원시 HTML 대신 그룹 블록이 되며, 블록 렌더링을 우회하지 않고 해당 요소를 보존합니다.
  • 매핑된 리치 텍스트 문단은 인라인 마크업을 유지하고, 이미지로만 구성된 문단은 매핑된 이미지 블록으로 변환되며, 단축 코드 태그는 콘텐츠를 보존합니다.
  • InnerBlocks, RichText 및 useBlockProps 요소의 속성을 포함해 이스케이프된 속성을 디코딩한 후 한 번만 이스케이프합니다.
  • 인용된 자체 닫는 태그 속성 안의 보다 큼 기호도 허용됩니다.
  • 전역 HTML 속성은 블록에서 필드로 선언하지 않은 경우 Blockstudio 블록의 루트에 전달됩니다. wp bs pages sync은 저장됐지만 렌더링되지 않은 속성을 보고합니다.

Blade 기반 페이지, 패턴, 사이트 편집기 템플릿이 이제 Blockstudio\Blade_Renderer을 통해 렌더링되어 illuminate/view 8부터 12까지를 지원합니다. 같은 블록을 대상으로 하는 모든 확장 파일이 등록되며, 우선순위, 그룹 필드, 대상 목록은 문서화된 스키마를 따릅니다.

중첩된 SCSS 종속 항목도 추적합니다. 다른 부분 템플릿에서 가져온 부분 템플릿을 편집하면 종속 스타일시트의 버전이 바뀌고 다시 컴파일됩니다.

PHPStan 개선 사항

별도로 설치하는 blockstudio/phpstan 패키지는 접두사 및 별칭 태그, 매핑된 페이지 요소, 레이아웃, 번들로 제공되는 UI 블록, 선택적으로 다른 프로젝트 PHP 소스까지 블록 태그 검증 범위를 확장합니다. 네임스페이스 해석은 하이픈이 포함된 네임스페이스를 비롯해 런타임과 일치하며, 전달된 전역 HTML 속성도 허용됩니다.

$a, $block, $context 같은 블록 템플릿 변수는 Blockstudio에서 정의된 것으로 처리됩니다. PHPStan 2.3에서 필드 유형은 null 병합과 isset()에서도 유지되며, 템플릿에서 자체 $a을 지정하면 지정한 유형이 유지됩니다.

이 변경 사항은 blockstudio/phpstan 0.1.9에서 제공됩니다. 플러그인과 별도로 패키지를 업데이트해야 하며, PHPStan 2.1.47 이상이 필요합니다:

셸
composer require --dev blockstudio/phpstan:^0.1.9

구성 및 분석 프리셋은 PHPStan를 참조하세요.

접근성 및 번역

번들로 제공되는 UI 트리거는 실제 버튼에 펼침 상태를 표시합니다. 체크박스, 스위치, 라디오 버튼의 레이블은 컨트롤에 이름을 부여하고 전환할 수 있습니다. 이동 경로, 페이지 매김, 탐색 메뉴, 표의 자식 요소 사이에 유효하지 않은 래퍼 요소를 삽입하지 않습니다.

암호 표시 전환 버튼은 눌림 상태를 표시하며 클릭 영역이 더 넓습니다. 입력란은 autocomplete을 허용하고, 암호 입력란에는 ID와 접근성 레이블을 명시적으로 지정할 수 있습니다. 캐러셀 뷰포트는 키보드로 포커스할 수 있으며, 스피너와 스켈레톤 애니메이션은 동작 감소 설정을 따릅니다.

편집기와 관리자 개요는 blockstudio 텍스트 도메인에 설치된 JavaScript 번역을 불러옵니다. 속성 메뉴와 자리 표시자, 코드 팝업 작업, 이미지 및 파일 배지를 이제 번역할 수 있습니다. 번역이 없는 문자열은 영어로 표시됩니다.

UI 라이브러리 및 번역 설정을 참조하세요.

문서 및 업그레이드

문서에는 문서 사이트, Content Sync, Site Editor 템플릿, 블록 태그, 아일랜드, 사용자 정의 필드 유형, 배포, 사전 렌더링, 레지스트리 설정, 분석 도구 및 UI 앱 화면에 관한 가이드가 추가됩니다. ACF 마이그레이션 가이드는 현재 ACF 등록 방식과 Block Bindings를 반영합니다.

사용자 정의 populate 예제는 이제 지원되는 단일 인수 명명 데이터셋 필터를 사용합니다. 에셋 문서에는 프런트엔드 스타일시트 순서와 블록 CSS 뒤에 테마 오버라이드를 불러오는 방법이 설명되어 있습니다. 기여자 설치에서는 레지스트리 인증 정보 없이 공개 Font Awesome 패키지를 사용합니다.

PHP 8.2와 WordPress 6.7이 계속 최소 요구 사항입니다. 가상 라우트와 새 유지보수 명령을 기존 페이지 컬렉션을 변경하지 않고 사용할 수 있습니다. 위의 옵션 저장 규칙을 확인하고, 사용 중이라면 별도의 PHPStan 패키지를 업데이트하세요. 페이지 동기화는 이전처럼 계속 명시적으로 실행해야 합니다.

7.7.1 후속 조치

7.7.1 패치는 동기화 결과를 더 명확하고 안전하게 만듭니다. 키 기반 병합으로 게시물이 변경되지 않으면 더 이상 리비전을 만들거나 수정 타임스탬프를 업데이트하지 않습니다. 기존 게시 상태는 유지되고, 파일이 관리하는 제목 및 슬러그 교체가 보고되며, 잠겼거나 삭제된 페이지는 CLI 보고서에 표시됩니다. Content Sync는 Page Sync가 관리하는 본문을 표시하고 기존 검토용 사본을 유지합니다. 또한 이 패치는 WordPress가 관리하는 속성이 충돌하는 필드 ID에 의해 덮어써지지 않도록 보호하고, 다른 필터가 추가한 편집기 클래스를 보존합니다.