워드프레스 차일드 테마 만들기: 부모 테마 수정 없이 안전하게 개발하는 방법

차일드 테마란?

차일드 테마는 기존 테마의 기능과 디자인을 이어받아 별도로 수정하는 하위 테마입니다. 기존 테마는 부모 테마라고 부릅니다.

예를 들어 기존 테마의 폴더가 다음과 같다고 가정하겠습니다.

/wp-content/themes/mytheme/

차일드 테마는 별도의 폴더에 생성합니다.

/wp-content/themes/mytheme-child/

차일드 테마를 활성화하면 부모 테마의 기본 구조를 그대로 사용합니다. 별도로 만든 CSS와 PHP 파일은 차일드 테마에서 관리합니다.

차일드 테마는 부모 테마를 대체하지 않습니다. 부모 테마 위에 수정 사항을 추가하는 방식입니다.

차일드 테마를 사용하는 이유

부모 테마의 파일을 직접 수정하면 다음 업데이트에서 파일이 새 버전으로 교체됩니다. 직접 작성한 CSS나 PHP 코드도 함께 사라질 수 있습니다.

예를 들어 다음 파일을 직접 수정했다고 가정하겠습니다.

/wp-content/themes/mytheme/functions.php

테마를 업데이트하면 수정한 내용이 새 파일로 덮어씌워질 수 있습니다.

차일드 테마를 사용하면 별도의 파일에 코드를 작성합니다.

/wp-content/themes/mytheme-child/functions.php

부모 테마가 업데이트되어도 차일드 테마 파일은 별도 폴더에 남습니다.

차일드 테마가 필요한 상황은 다음과 같습니다.

페이지 디자인만 잠깐 수정하는 상황이라면 관리자 설정으로 해결할 수 있습니다. 테마 파일을 직접 건드리는 작업이라면 차일드 테마를 사용합니다.

부모 테마 폴더 이름 확인

차일드 테마를 만들려면 먼저 부모 테마의 실제 폴더 이름을 확인합니다.

워드프레스 테마는 일반적으로 다음 경로에 설치됩니다.

/wp-content/themes/

부모 테마 경로가 다음과 같다면:

/wp-content/themes/mytheme/

폴더 이름은 다음과 같습니다.

mytheme

이 이름은 차일드 테마의 style.css에서 부모 테마를 지정할 때 사용합니다.

Template: mytheme

Template에는 관리자 화면에 보이는 테마 이름이 아니라 서버의 폴더 이름을 입력합니다.

예를 들어 관리자 화면의 테마 이름이 다음과 같더라도:

My Business Theme

실제 폴더 이름이 mytheme라면 다음처럼 작성합니다.

Template: mytheme

부모 테마 폴더 이름이 다르면 차일드 테마는 정상적으로 연결되지 않습니다.

차일드 테마 폴더와 style.css 생성

부모 테마 폴더 이름을 확인했다면 차일드 테마 폴더를 생성합니다.

/wp-content/themes/mytheme-child/

폴더 이름은 반드시 -child로 끝날 필요는 없습니다. 다만 부모 테마와 구분하기 쉬운 이름을 사용하면 관리가 편합니다.

다음으로 차일드 테마 폴더에 style.css 파일을 만듭니다.

/wp-content/themes/mytheme-child/style.css

파일에는 다음 내용을 작성합니다.

/*
Theme Name: MyTheme Child
Description: MyTheme 부모 테마를 확장하는 차일드 테마입니다.
Author: Ible
Author URI: https://ible.blog/
Template: mytheme
Version: 1.0.0
Text Domain: mytheme-child
*/
/* 차일드 테마의 사용자 정의 CSS를 아래에 작성합니다. */

각 항목의 역할은 다음과 같습니다.

차일드 테마 등록에 필요한 핵심 항목은 다음 두 가지입니다.

/*
Theme Name: MyTheme Child
Template: mytheme
*/

style.css 파일만 있어도 워드프레스가 차일드 테마를 인식할 수 있습니다. functions.php는 CSS 등록이나 PHP 기능 추가가 필요할 때 생성합니다.

워드프레스 공식 문서에서도 style.css의 Template 값이 부모 테마 폴더 이름과 정확히 일치해야 한다고 설명합니다. WordPress 공식 문서: Child Themes

functions.php에서 스타일 적용

부모 테마에 따라 차일드 테마의 style.css가 자동으로 로드되지 않을 수 있습니다. 이때 functions.php에서 스타일 파일을 등록합니다.

차일드 테마 폴더에 다음 파일을 생성합니다.

/wp-content/themes/mytheme-child/functions.php

파일에는 다음 코드를 작성합니다.

<?php
/**
 * 차일드 테마의 기능을 등록합니다.
 */

/**
 * 차일드 테마의 style.css 파일을 불러옵니다.
 */
function ible_enqueue_child_theme_styles() {
    // 차일드 테마 style.css 파일의 실제 서버 경로입니다.
    $stylesheet_path = get_stylesheet_directory() . '/style.css';

    // CSS 파일이 없다면 실행을 중단합니다.
    if ( ! file_exists( $stylesheet_path ) ) {
        return;
    }

    // 차일드 테마의 스타일 파일을 워드프레스에 등록합니다.
    wp_enqueue_style(
        // 스타일 파일을 구분하는 고유 이름입니다.
        'ible-child-theme-style',
        // 현재 활성화된 테마의 style.css 주소입니다.
        get_stylesheet_uri(),
        // 별도로 지정한 의존성은 없습니다.
        array(),
        // CSS 파일 수정 시간을 버전으로 사용합니다.
        filemtime( $stylesheet_path )
    );
}
// 일반적인 부모 테마 스타일 로드 이후에 실행합니다.
add_action(
    'wp_enqueue_scripts',
    'ible_enqueue_child_theme_styles',
    20
);

코드에 사용한 함수는 다음과 같습니다.

filemtime()은 CSS 파일 수정 시간을 버전으로 사용합니다. 파일을 변경하면 브라우저가 이전 버전의 CSS를 계속 사용하는 문제를 줄일 수 있습니다.

이미 functions.php 파일이 있다면 기존 코드는 그대로 유지합니다. `<?php`가 이미 선언되어 있다면 다시 작성하지 않습니다.

부모 테마 스타일이 적용되지 않는 경우도 있습니다. 일부 부모 테마는 현재 활성화된 테마의 CSS만 불러옵니다. 차일드 테마를 활성화하면 부모 테마의 스타일이 빠질 수 있습니다.

이 경우 부모 테마의 style.css를 추가로 등록합니다.

<?php
/**
 * 부모 테마의 style.css 파일을 불러옵니다.
 */
function ible_enqueue_parent_theme_styles() {
    // 부모 테마의 style.css 파일 주소를 가져옵니다.
    $parent_stylesheet = get_parent_theme_file_uri( 'style.css' );

    // 부모 테마 스타일을 워드프레스에 등록합니다.
    wp_enqueue_style(
        // 부모 테마 스타일을 구분하는 고유 이름입니다.
        'ible-parent-theme-style',
        // 부모 테마 style.css 파일의 주소입니다.
        $parent_stylesheet
    );
}
// 일반적인 스타일 등록 시점보다 먼저 실행합니다.
add_action(
    'wp_enqueue_scripts',
    'ible_enqueue_parent_theme_styles',
    5
);

부모 테마와 차일드 테마의 CSS가 이미 정상적으로 표시된다면 위 코드는 추가하지 않습니다. 같은 스타일을 중복 등록하면 파일이 불필요하게 여러 번 로드될 수 있습니다.

워드프레스에서 차일드 테마 활성화

차일드 테마 파일을 작성했다면 관리자 화면에서 활성화합니다.

① 워드프레스 관리자에 로그인합니다. ② 외모 → 테마로 이동합니다. ③ MyTheme Child를 찾습니다. ④ 활성화를 선택합니다. ⑤ 사이트 화면에서 디자인을 확인합니다.

테마 목록에는 style.css의 Theme Name 값이 표시됩니다.

Theme Name: MyTheme Child

차일드 테마를 활성화해도 부모 테마는 삭제하지 않습니다. 부모 테마가 설치되어 있어야 차일드 테마가 정상적으로 실행됩니다.

활성화 후 기존 디자인이 유지된다면 차일드 테마 연결이 완료된 상태입니다.

차일드 테마 CSS 적용도 확인해볼 수 있습니다. style.css에 테스트용 코드를 추가하면 적용 여부를 쉽게 확인할 수 있습니다.

/*
Theme Name: MyTheme Child
Template: mytheme
Version: 1.0.0
*/

/* 사이트 제목 색상을 변경합니다. */
.site-title {
    color: #173a56;
}

/* 기본 버튼의 배경색과 글자색을 변경합니다. */
.custom-button {
    background-color: #173a56;
    color: #ffffff;
}

브라우저에서 변경 내용이 표시되면 차일드 테마 CSS가 정상적으로 적용된 것입니다.

.site-title이나 .custom-button은 예시 클래스입니다. 실제 사이트에 존재하는 클래스 이름으로 변경해 사용합니다.

특정 페이지에 커스텀 템플릿 추가

차일드 테마에는 특정 페이지에만 적용되는 PHP 템플릿도 만들 수 있습니다.

예를 들어 문의 페이지 주소가 다음과 같다고 가정하겠습니다.

https://example.com/contact/

슬러그는 페이지 주소에서 도메인 뒤에 붙는 고유 문자열입니다. 위 페이지의 슬러그는 contact입니다.

차일드 테마에 다음 파일을 생성합니다.

/wp-content/themes/mytheme-child/page-contact.php

파일에는 다음 코드를 작성합니다.

<?php
/**
 * 문의 페이지 전용 템플릿입니다.
 */

// 현재 테마의 헤더를 불러옵니다.
get_header();
?>

<main id="primary" class="site-main contact-page">
    <?php
    // 현재 페이지의 데이터를 확인합니다.
    while ( have_posts() ) :
        // 페이지 제목과 본문을 사용할 수 있도록 준비합니다.
        the_post();
        ?>
        <section class="contact-page__content">
            <div class="container">
                <h1>
                    <?php
                    // 페이지 제목을 안전하게 출력합니다.
                    echo esc_html( get_the_title() );
                    ?>
                </h1>
                <div class="contact-page__body">
                    <?php
                    // 관리자에서 작성한 페이지 본문을 출력합니다.
                    the_content();
                    ?>
                </div>
            </div>
        </section>
        <?php
    // 페이지 콘텐츠 출력을 종료합니다.
    endwhile;
    ?>
</main>

<?php
// 현재 테마의 푸터를 불러옵니다.
get_footer();
?>

사용한 함수는 다음과 같습니다.

page-contact.php는 contact 페이지에 자동으로 적용됩니다. 별도의 Template Name 주석을 추가할 필요는 없습니다.

페이지 템플릿의 작동 원리와 적용 순서는 워드프레스 특정 페이지에 커스텀 템플릿 적용하는 방법에서 자세히 확인할 수 있습니다.

차일드 테마 오류 해결

차일드 테마가 표시되지 않거나 디자인이 깨지는 문제는 대부분 파일 위치, 부모 테마 연결 또는 CSS 로드와 관련되어 있습니다.

차일드 테마가 목록에 나타나지 않는 경우, style.css는 차일드 테마의 최상위 폴더에 저장합니다.

정상 경로:
/wp-content/themes/mytheme-child/style.css

다음처럼 별도 폴더에 저장하면 워드프레스가 인식하지 않습니다.

잘못된 경로:
/wp-content/themes/mytheme-child/css/style.css

파일 상단에 다음 항목이 있는지도 확인합니다.

/*
Theme Name: MyTheme Child
Template: mytheme
*/

부모 테마를 찾을 수 없다는 오류는 Template 값이 부모 테마의 실제 폴더 이름과 다르면 발생합니다.

부모 테마가 다음 위치에 있다면:

/wp-content/themes/mytheme/

설정은 다음과 같아야 합니다.

Template: mytheme

관리자 화면의 테마 이름을 그대로 넣으면 연결되지 않을 수 있습니다.

Template: MyTheme Premium

CSS가 적용되지 않는 경우, 차일드 테마의 style.css가 등록되어 있는지 확인합니다.

<?php
/**
 * 차일드 테마 스타일을 불러옵니다.
 */
function ible_load_child_styles() {
    // 현재 활성화된 차일드 테마의 style.css를 등록합니다.
    wp_enqueue_style(
        'ible-child-style',
        get_stylesheet_uri()
    );
}
// 프런트엔드 스타일 로드 시점에 함수를 실행합니다.
add_action(
    'wp_enqueue_scripts',
    'ible_load_child_styles'
);

브라우저 개발자 도구에서 CSS 파일이 로드되는지도 확인합니다.

스타일 파일이 정상적으로 로드된다면 CSS 선택자가 실제 HTML 구조와 일치하는지 살펴봅니다.

functions.php 수정 후 사이트에 오류가 발생하는 경우도 있습니다. PHP 시작 태그를 중복으로 입력하면 오류가 발생합니다.

<?php
<?php

같은 함수를 두 번 선언해도 오류가 발생합니다.

<?php
function custom_styles() {
    // 첫 번째 함수입니다.
}

function custom_styles() {
    // 같은 이름을 다시 사용하면 오류가 발생합니다.
}

함수 이름에 프로젝트 접두사를 붙이면 충돌을 줄일 수 있습니다.

<?php
function ible_custom_styles() {
    // 아이블 사이트 전용 스타일을 등록합니다.
}

사이트 접속이 중단되면 서버 파일 관리자나 SFTP로 functions.php를 수정합니다. 마지막으로 추가한 코드를 제거하면 이전 상태로 복구할 수 있��니다.