본문으로 건너뛰기
테마

워드프레스 자식 테마 스타일이 로드되지 않을 때

자식 테마의 style.css가 로드되지 않는 이유는 워드프레스가 이 파일을 자동으로 enqueue하지 않기 때문입니다. 자식 테마의 스타일시트는 자식 테마의

게시됨

자식 테마의 style.css가 로드되지 않는 이유는 워드프레스가 이 파일을 대신 enqueue해 주지 않기 때문입니다. 자식 테마의 스타일시트는 자식 테마의 functions.php에서 직접 등록해 줘야 하는데, 이 enqueue 코드에는 거의 항상 두 가지 버그 중 하나가 있습니다. 아예 코드가 없거나, 부모 스타일시트를 의존성으로 선언하지 않은 채 로드되어 규칙이 캐스케이드에서 엉뚱한 위치에 놓여 덮어써지는 것입니다. enqueue만 바로잡으면 스타일이 돌아옵니다. 2013년쯤 튜토리얼에서 복사해 왔을 법한 예전 @import 방식은 잘못된 해결책입니다.

왜 이런 일이 생기는가

전형적인 자식 테마는 두 개의 필수 파일로 이루어집니다. 부모를 지정하는 헤더 블록이 담긴 style.css, 그리고 functions.php입니다. 헤더의 Template: 줄은 워드프레스에게 어떤 부모로부터 템플릿을 상속받을지 알려줍니다. 워드프레스가 자동으로 해 주는 건 딱 이것뿐입니다. 헤더를 읽고 템플릿 폴백을 연결한 뒤 거기서 멈춥니다. 프런트엔드에서 자식 style.css를 enqueue해 주는 일은 절대 없습니다.

한편 부모 테마는 자신의 functions.php에서 wp_enqueue_scripts에 훅을 걸어 자기 스타일시트를 enqueue합니다. 자식 functions.php가 먼저 실행되고, 그다음 부모 것이 실행된 뒤, 그 훅에 걸린 모든 것이 발동됩니다. 자식이 자기 파일에 대해 wp_enqueue_style을 한 번도 호출하지 않으면 브라우저는 그 파일을 절대 요청하지 않습니다. 페이지가 부모 테마 원본 그대로 보이는 이유는, 실제로 딱 그 상태이기 때문입니다.

두 번째 실패는 더 미묘합니다. 자식 스타일시트를 enqueue했고 로드도 되는데, 재정의(override)한 규칙이 전혀 먹히지 않는 경우입니다. 이건 로드 순서 문제입니다. 두 규칙의 명시도(specificity)가 같으면, 나중에 로드된 쪽이 이깁니다. 자식 CSS가 부모보다 먼저 로드되면 동점 상황에서 매번 부모가 이깁니다. wp_enqueue_style의 의존성 배열이 바로 이 순서를 강제하는 장치입니다.

사람들이 또 하나 자주 틀리는 것: get_template_directory_uri()는 부모 테마 폴더를 가리키고, get_stylesheet_directory_uri()는 활성화된(자식) 테마 폴더를 가리킵니다. 이 둘을 바꿔 쓰면 부모의 style.css를 한 번 더 enqueue하게 되고, 정작 자식 것은 건드리지도 않게 됩니다.

순서대로 해결하기

먼저, 실제로 무엇이 로드되고 있는지 확인합니다. 문제가 생긴 페이지를 열고 소스 보기를 한 뒤, 자식 테마 폴더 이름으로 검색해 보세요. 워드프레스는 enqueue된 스타일을 <link id="handle-css" href="..."> 형태로 렌더링합니다. 여기서 id는 여러분의 핸들 뒤에 -css가 붙은 값입니다. 자식 style.css가 <head>에 아예 없다면 enqueue가 실행되지 않는 것입니다. 있는데도 스타일이 적용되지 않는다면 의존성/순서 문제입니다. 이 한 번의 확인으로 두 버그 중 어느 쪽인지 알 수 있습니다.

둘째, 부모의 실제 핸들을 찾습니다. 요즘 나오는 대부분의 테마(Astra, GeneratePress, Twenty-* 시리즈)는 이미 자신의 스타일시트를 특정 핸들로 enqueue하고 있습니다. astra-theme-css, generate-style-css, twenty-twenty-four-style 같은 식이죠. 여러분에게 필요한 건 바로 그 정확한 문자열입니다. 부모 테마를 grep하거나, 소스 보기에서 <link id="...-css">를 읽어(끝의 -css를 떼어내고) 확인하세요.

셋째, enqueue 코드를 작성합니다. 부모가 이미 자신의 스타일시트를 로드하는 일반적인 경우에는, 부모를 다시 enqueue하지 않습니다. 자식만 enqueue하되, 부모의 핸들을 의존성으로 나열하여 자식이 그 뒤에 로드되도록 합니다.

<?php
add_action( 'wp_enqueue_scripts', 'child_enqueue_styles', 20 );

function child_enqueue_styles() {
    wp_enqueue_style(
        'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array( 'astra-theme-css' ), // <-- the parent's REAL handle
        wp_get_theme()->get( 'Version' )
    );
}

부모 테마가 자신의 스타일시트를 enqueue하지 않는 경우(일부 오래되었거나 미니멀한 테마는 @import에 의존합니다)에는, 둘 다 enqueue하고 자식이 부모에 의존하도록 만듭니다.

<?php
add_action( 'wp_enqueue_scripts', 'child_enqueue_styles' );

function child_enqueue_styles() {
    wp_enqueue_style(
        'parent-style',
        get_template_directory_uri() . '/style.css'
    );
    wp_enqueue_style(
        'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array( 'parent-style' ),
        wp_get_theme()->get( 'Version' )
    );
}

wp_get_theme()->get('Version') 인자는 캐시 무효화(cache-buster) 역할을 합니다. 자식 style.css 헤더의 Version: 줄을 올리면 브라우저가 파일을 다시 받아옵니다. 이걸 빼먹으면 CSS를 수정해 놓고도 아무 변화가 없다며 애먹게 되는데, 알고 보면 그냥 캐시된 것입니다.

functions.php에 문법 오류가 있으면 파일 전체가 조용히 죽어 버려 어떤 enqueue도 실행되지 않습니다. 이건 정확히 “스타일이 로드되지 않음”처럼 보입니다. WP_DEBUG를 켜거나, debug.log를 우리 워드프레스 오류 로그 해독기에 붙여넣어 치명적 오류를 빠르게 찾아내세요.

하지 말아야 할 것

@import를 쓰지 마세요. Codex 시절의 조언은 자식 style.css 맨 위에 @import url("../parenttheme/style.css");를 넣으라는 것이었습니다. 작동은 하지만 느립니다. 브라우저가 자식 CSS를 파싱하기 전까지는 부모 CSS 다운로드를 시작할 수 없어서, 두 요청이 병렬이 아니라 직렬로 실행됩니다. 워드프레스 공식 핸드북도 수년째 이 방식을 권장하지 않고 있습니다. 튜토리얼이 이렇게 하라고 했다면, 스타일이 버벅이는 건 바로 그 튜토리얼 때문입니다.

핸들을 'parent-style'로 하드코딩해서 부모 파일을 무작정 enqueue하지 마세요. 그 유명한 Codex 스니펫이 정확히 이렇게 하는데, 이미 다른 핸들로 스타일시트를 등록해 둔 테마라면 어떤 것이든 잘못됩니다. 결국 부모 CSS를 두 번 로드하게 되고, 의존성은 존재하지도 않을 수 있는 핸들을 가리키게 됩니다.

functions.php의 최상위(top level)에서 wp_enqueue_style을 호출하지 마세요. 반드시 wp_enqueue_scripts에 훅을 건 함수 안에서 실행되어야 합니다. 너무 일찍 호출되면 아무 일도 일어나지 않습니다.

부모의 functions.php 전체를 자식에 복사하지 마세요. 둘 다 로드되며, 자식 것이 먼저 실행됩니다. 이걸 복사하면 함수 중복 선언이 생겨 치명적 오류가 납니다.

한 가지 주의할 점: 지금까지의 내용은 모두 클래식(PHP 템플릿) 테마에 관한 것입니다. 부모가 블록 테마라면 스타일은 대부분 theme.json과 사이트 편집기(Site Editor)를 통해 흐르며, style.css 재정의 동작 방식도 다릅니다. 그런 경우라면 저라면 이 내용을 덜 신뢰하고, 이 enqueue가 해결책이라고 가정하기보다 직접 테스트해 보겠습니다.

그래도 안 될 때

자식 style.css 헤더의 Template: 줄이 부모의 폴더 이름과 대소문자까지 정확히 일치하는지 확인하세요. 부모의 표시 이름(display name)이 아니라 폴더 이름입니다. 그런 다음 소스 보기를 다시 확인하세요. 핸들이 있는지, 부모 뒤에 로드되는지, 버전 쿼리 문자열이 올라갔는지. <link>가 있고, 가장 나중에 로드되며, 그런데도 CSS가 여전히 적용되지 않는다면, 이건 더 이상 enqueue 문제가 아니라 명시도(specificity) 문제입니다. 이때는 해결의 초점이 규칙 자체로 옮겨갑니다.