블록 템플릿이 적용되지 않나요? 데이터베이스부터 보세요

템플릿 파일이 무시되는 이유는 거의 확실히 데이터베이스의 사본이 이기고 있기 때문입니다. 사이트 편집기에서 템플릿을 열고 저장을 누르는 순간 워드프레스는 wp_template 글 레코드를 기록하고, 그때부터 테마 폴더의 .html 파일 대신 그 레코드를 제공합니다. 그래서 이후에 파일을 아무리 고쳐도 프런트엔드에는 보이지 않습니다. 그 레코드를 지우는 것이 해결책이며, 계층 구조나 파일명, 캐시를 건드리기 전에 가장 먼저 확인할 일입니다.

데이터베이스 사본이 있는지 확인하기

외모 → 편집기 → 템플릿으로 이동하세요. 워드프레스가 데이터베이스에서 제공하고 있는 템플릿은 목록에 표시가 붙습니다. 워드프레스 버전에 따라 배지에 “사용자 정의됨”이라고 적히거나, 그런 이름의 필터 아래에 템플릿이 모입니다. 그 배지가 곧 답입니다. 배지가 있다면 여러분의 파일은 쓰이고 있지 않습니다.

명령줄에서도 같은 것을 확인할 수 있는데, 더 빠르고 사이트 편집기가 말썽일 때도 동작합니다.

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

각 행이 하나의 데이터베이스 오버라이드입니다. post_name은 템플릿 슬러그와 일치하므로, single이라는 이름의 행은 templates/single.html을 가리고 있는 것입니다.

사람들이 자주 걸려 넘어지는 지점이 하나 있습니다. 이 레코드들은 경로가 아니라 분류 용어를 통해 테마와 연결됩니다. 테마 폴더 이름을 바꾸면 저장된 템플릿은 데이터베이스에 남아 있지만 활성 테마와 더 이상 매칭되지 않고, 사이트는 갑자기 파일로 되돌아갑니다. 이것은 “내 파일이 무시된다”가 아니라 “내 커스터마이징이 사라졌다”처럼 보입니다. 같은 원리의 정반대 증상입니다.

지우기

사이트 편집기에서 템플릿의 옵션 메뉴(옆의 점 세 개)를 열고 커스터마이징 지우기를 선택하세요. 버전에 따라 재설정으로 표기되기도 합니다. 이렇게 하면 데이터베이스 레코드가 삭제되고 통제권이 디스크의 파일로 돌아갑니다.

메뉴에 커스터마이징 지우기나 재설정 대신 삭제가 보인다면, 그 템플릿은 데이터베이스에만 존재하고 뒤에 파일이 없는 것입니다. 삭제하면 템플릿이 완전히 사라지고 워드프레스는 계층 구조를 따라 아래로 내려갑니다.

WP-CLI에서는 위 목록의 ID를 써서 이렇게 합니다.

wp post delete 482 --force

여기서 치르는 비용에 대해 스스로 솔직해지세요. 커스터마이징 지우기는 그 템플릿에 대해 사이트 편집기에서 만들어 둔 모든 것을 영구히 버리며, 되돌릴 수 없습니다. 사이트 편집기 버전에 실제 작업물이 들어 있다면 블록 마크업을 먼저 복사해 두세요. 편집기에서 템플릿을 열어 코드 보기로 전환한 뒤, 그 내용을 .html 파일에 붙여 넣으면 됩니다. 그러면 파일이 단일 기준점이 되고 잃는 것도 없습니다.

워드프레스가 템플릿을 고르는 방식

블록 테마는 클래식 테마와 같은 계층 구조 논리를 쓰되, 테마 루트의 .php 파일 대신 templates/의 .html 파일을 씁니다. 워드프레스는 가장 구체적인 것부터 가장 일반적인 것까지 훑어 내려가며 처음 발견한 파일을 사용합니다.

보고 있는 대상	확인 순서
개별 글	single-post-{slug}.html → single-post.html → single.html → singular.html → index.html
페이지	page-{slug}.html → page-{id}.html → page.html → singular.html → index.html
카테고리 아카이브	category-{slug}.html → category-{id}.html → category.html → archive.html → index.html
커스텀 글 타입	single-{post-type}.html → single.html → singular.html → index.html
404 페이지	404.html → index.html

이 순서를 통째로 무시하게 만드는 것이 두 가지 있습니다. 첫째는 위에서 설명한 데이터베이스 레코드입니다. 둘째는 글이나 페이지에 직접 지정된 템플릿입니다. 글 편집기를 열어 사이드바의 템플릿 패널을 보고 특정 템플릿이 선택되어 있는지 확인하세요. 명시적 지정은 언제나 계층 구조를 이기며, 일부러 찾아보지 않으면 눈에 띄지 않습니다.

슬러그 기반 템플릿이 얼마나 약한지는 몸에 새겨둘 만합니다. page-about.html은 페이지 슬러그가 about인 동안에만 매칭됩니다. 페이지 이름을 about-us로 바꾸면 경고도 오류도 없이 템플릿 적용이 멈춥니다.

템플릿과 템플릿 파트

템플릿은 화면 전체를 렌더링하며 계층 구조에 의해 선택됩니다. 템플릿 파트는 헤더, 푸터, 사이드바 같은 조각으로, 템플릿이 불러다 씁니다. 파트는 parts/에, 템플릿은 templates/에 있고, 데이터베이스에도 wp_template_part 레코드로 따로 저장됩니다.

흔한 혼란은 이렇습니다. 헤더를 고쳤는데 건드릴 생각도 없던 페이지에 변화가 나타납니다. 그것이 정상 동작입니다. 하나의 파트를 그것을 포함하는 모든 템플릿이 공유합니다. 특정 템플릿에서만 다른 헤더를 쓰고 싶다면 두 번째 파트 파일과 그것을 참조하는 템플릿이 필요합니다. 공유되는 파트를 수정하는 것으로는 템플릿별 차이를 절대 만들 수 없습니다.

반대 경우도 있습니다. 페이지 전체 레이아웃을 parts/에 넣어 두고 왜 계층 구조가 집어가지 않는지 의아해하는 경우입니다. 파트는 애초에 계층 구조의 후보가 아니며, 어떤 요청도 파트로 직접 연결되지 않습니다.

파일 이름과 위치

더 특이한 원인을 의심하기 전에 이것들부터 확인하세요.

• 폴더는 테마 루트의 templates/이며 복수형입니다. template/도, block-templates/도 아닙니다. block-templates/는 블록 테마가 코어에 들어오기 전 구텐베르크 플러그인 시절의 올바른 이름이었고 아직도 많은 튜토리얼이 이렇게 안내하지만, 현재 워드프레스에서는 동작하지 않습니다.
• 템플릿 파트는 parts/에 들어갑니다. template-parts/가 아닙니다(그쪽은 PHP 조각을 두는 클래식 테마 관례입니다).
• 확장자는 .html입니다. templates/에 있는 .php 파일은 무시됩니다.
• 파일명은 소문자에 하이픈을 씁니다. single-Post.html이나 single_post.html은 매칭되지 않습니다. macOS처럼 대소문자를 구분하지 않는 파일 시스템에서는 로컬에서 잘 되다가 리눅스 서버에서 깨지는, 전형적인 “내 컴퓨터에서는 되는데” 상황이 벌어집니다.
• templates/index.html은 반드시 있어야 합니다. 없으면 워드프레스가 그 테마를 블록 테마로 분류하지 않고, 사이트 편집기가 아예 나타나지 않을 수도 있습니다.
• 자식 테마에서 작업 중이라면 자식 테마의 템플릿이 부모보다 우선합니다. 자식 테마에 남아 있던 파일 하나가 여러분이 고치고 있는 부모 파일을 조용히 이깁니다.

글 편집기에서 선택할 수 있어야 하는 커스텀 템플릿은 theme.json의 customTemplates에 파일 기본 이름, 사람이 읽을 제목, 적용할 글 타입을 함께 선언해야 합니다. 이 항목이 없으면 파일은 존재하지만 템플릿 패널에 절대 나타나지 않습니다.

캐시 — 마지막에 확인하세요

캐시 문제는 실재하지만 가능성이 가장 낮은 원인이며, 여기부터 손대다가 오후를 통째로 날리게 됩니다.

페이지 캐시를 비우고, Redis나 Memcached 같은 지속형 객체 캐시를 쓴다면 그것도 함께 비우세요. 템플릿 해석 결과가 거기에 남아 있을 수 있습니다. 그런 다음 브라우저 캐시를 무시하고 새로고침하세요.

도움이 되지 않는 것은 OPcache 비우기입니다. 블록 템플릿은 .html 파일이고 PHP로 컴파일되지 않으므로 OPcache와는 아무 상관이 없습니다. 예전에 OPcache를 비웠더니 해결된 것처럼 보였다면, 같은 시점에 다른 무언가가 바뀐 것입니다.

그래도 막혔다면

데이터베이스 레코드도 없고, 파일명도 맞고, 글에 명시적 템플릿 지정도 없고, 캐시도 이미 비웠다면 플러그인을 보세요. 페이지 빌더, 멤버십 플러그인, 다국어 플러그인, LMS처럼 템플릿 해석에 필터를 거는 것은 무엇이든 요청 후반부에 자기 템플릿을 끼워 넣을 수 있습니다. 기본 블록 테마로 바꾸고 플러그인을 모두 끈 상태로 시험한 뒤, 하나씩 다시 켜보세요.

그리고 템플릿이 적용은 되는데 빈 화면으로 렌더링된다면 그건 다른 문제입니다. 파일 안의 블록 마크업이 유효한지 확인하세요. 블록 주석이 잘못되면 편집기가 오류를 내는 대신 내용을 조용히 걷어낼 수 있습니다.