워드프레스 테마 자식 테마(Child Theme) 생성해 코드 안전 관리하는 법｜style.css·functions.php 설정과 업데이트 보호

1. 워드프레스 자식 테마가 필요한 이유와 작동 원리

워드프레스 자식 테마는 다른 테마를 부모로 지정하여 부모 테마의 기능과 디자인을 상속받는 확장 테마입니다. 워드프레스 공식 개발자 문서도 부모 테마를 직접 수정하지 않으면서 변경 사항을 관리할 수 있다는 점을 주요 장점으로 설명합니다.

① 부모 테마 직접 수정의 위험

부모 테마의 파일은 제작사가 업데이트할 때 교체될 수 있습니다. 예를 들어 부모 테마의 functions.php에 추적 코드나 스타일 로딩 함수를 직접 추가했다면 업데이트 시 수정한 부분이 사라질 수 있습니다.

반면 자식 테마 폴더에 별도로 작성한 코드는 통상적인 부모 테마 업데이트에서 덮어써지지 않습니다.

② 자식 테마가 상속하는 것

자식 테마는 자체적으로 교체하거나 확장하지 않은 부분에 대해 부모 테마의 기능과 디자인을 사용합니다.

필요한 경우 특정 템플릿과 스타일을 자식 테마에서 정의하여 부모의 해당 동작을 변경할 수 있습니다.

③ 자식 테마가 모든 코드를 보호하지는 않습니다

자식 테마의 코드가 부모 업데이트에서 유지된다고 해도 부모 테마의 구조나 CSS 선택자, 사용 중인 함수가 변경되면 호환 문제가 발생할 수 있습니다.

따라서 자식 테마는 업데이트 덮어쓰기 위험을 줄이는 방법이지 테스트와 백업을 대신하는 자동 안전장치는 아닙니다.

④ 자식 테마와 플러그인의 역할 구분

색상, 헤더, 템플릿과 같이 현재 테마의 표현에 연결된 코드는 자식 테마로 관리하기 적합합니다.

반면 테마를 바꿔도 유지되어야 하는 회원 기능, 비즈니스 로직, 고유 콘텐츠 유형과 사이트 전반의 기능은 별도 플러그인으로 관리하는 편이 좋습니다.

2. Child Theme 폴더와 style.css 생성 방법

워드프레스 공식 개발자 문서에 따르면 자식 테마를 인식시키는 핵심 파일은 style.css이며, 그 파일의 테마 헤더에 Template 항목을 정확하게 작성해야 합니다.

① 부모 테마 폴더 이름부터 확인하기

FTP·SFTP 또는 호스팅 파일 관리자를 열고 다음 경로로 이동합니다.

예를 들어 부모 테마의 폴더명이 twentytwentyfour라면 자식 테마의 Template 값은 정확히 twentytwentyfour여야 합니다.

테마 화면에 표시되는 이름인 ‘Twenty Twenty-Four’를 적거나 자식 테마의 폴더명을 입력하는 것은 잘못된 설정입니다.

② 자식 테마 전용 폴더 생성

부모 테마 폴더와 같은 위치에 새 폴더를 만듭니다. 예시에서는 my-site-child라는 이름을 사용합니다.

wp-content/
└── themes/
 ├── twentytwentyfour/
 └── my-site-child/
 ├── style.css
 └── functions.php

위 구조에서 functions.php는 스타일을 명시적으로 로드하거나 PHP 기능을 추가할 때 사용하는 파일입니다. 자식 테마 인식을 위한 필수 파일은 style.css이며, 모든 자식 테마가 반드시 별도의 functions.php를 필요로 하는 것은 아닙니다.

③ style.css에 필수 헤더 작성

/*
Theme Name: My Site Child
Template: twentytwentyfour
Version: 1.0.0
Text Domain: my-site-child
*/

/* 여기에 사용자 정의 CSS를 작성합니다. */

Theme Name에는 관리자에 표시할 자식 테마 이름을 지정합니다. Template은 부모 테마 폴더명을 정확하게 입력합니다. Version과 Text Domain은 관리와 번역에 도움이 되는 선택적인 헤더입니다.

부모 테마가 Astra라면 Template: astra, GeneratePress라면 Template: generatepress처럼 실제 설치 폴더명에 맞게 변경해야 합니다.

④ 사용자 정의 CSS 작성 예시

테마가 해당 CSS 파일을 로드하도록 설정된 상태라면 다음과 같은 사용자 정의 스타일을 추가할 수 있습니다.

/* 글 본문 안의 링크 스타일 예시 */
.entry-content a {
 text-decoration-thickness: 2px;
 text-underline-offset: 3px;
}

/* 모바일에서 사용자 정의 영역 여백 조절 */
@media (max-width: 767px) {
 .my-custom-section {
 padding: 16px;
 }
}

선택자 이름은 사용 중인 테마의 실제 HTML 구조에 따라 달라질 수 있습니다. 코드를 넣기 전에 브라우저 개발자 도구에서 해당 요소의 클래스를 확인하세요.

⑤ style.css 파일 생성 시 주의사항

파일명은 정확히 style.css이어야 합니다. 메모장 사용 시 style.css.txt로 저장되지 않았는지도 확인하세요.

또한 테마 헤더를 CSS 주석 형식 안에 작성해야 하며, PHP 코드를 이 파일에 넣어서는 안 됩니다.

3. functions.php로 부모·자식 테마 CSS 안전하게 연결하기

자식 테마를 처음 만들 때 가장 많이 헷갈리는 부분은 부모와 자식 테마의 CSS를 어떤 순서로 불러와야 하는가입니다.

워드프레스 공식 개발자 문서는 테마에 따라 이미 스타일시트를 로드하는 방법이 다르므로 부모 테마의 기존 코드를 확인해야 한다고 설명합니다.

① 부모 테마가 자식 CSS까지 로드한다면 추가 코드가 필요하지 않습니다

일부 부모 테마는 자식 테마가 활성화되었을 때 부모와 자식의 스타일시트를 모두 자동으로 로드합니다.

이런 테마에 동일한 enqueue 코드를 중복 작성하면 CSS가 여러 번 로드될 수 있습니다.

따라서 가장 먼저 부모 테마의 functions.php와 스타일 로딩 함수, 공식 자식 테마 문서를 확인하세요.

② 자식 테마 style.css만 추가로 로드하는 예시

부모 테마가 자신의 스타일은 로드하지만 자식 테마의 style.css는 로드하지 않는 경우에는 자식 테마의 functions.php에 다음과 같은 코드를 추가할 수 있습니다.

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

function my_site_child_enqueue_styles() {
 wp_enqueue_style(
 'my-site-child-style',
 get_stylesheet_uri(),
 array(),
 wp_get_theme()->get('Version')
 );
}

위 코드는 현재 활성화된 자식 테마의 style.css를 프런트엔드에 등록하는 예시입니다.

wp_enqueue_scripts는 스타일과 스크립트를 로드할 때 사용하는 워드프레스 훅입니다.

get_stylesheet_uri()는 활성화된 테마의 기본 CSS 파일 주소를 반환합니다. 자식 테마가 활성화된 상태라면 자식 테마의 CSS를 가리킵니다.

③ 부모 CSS를 추가로 불러와야 하는 경우

부모 테마가 get_stylesheet_uri()를 사용해 활성 테마의 스타일시트만 불러오도록 만들어져 있다면 자식 테마 활성화 이후 부모 CSS가 빠질 수도 있습니다.

이런 구조에서는 자식 테마에서 부모 스타일을 별도로 로드하도록 구성할 수 있습니다.

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

function my_site_child_enqueue_parent_style() {
 wp_enqueue_style(
 'my-site-parent-style',
 get_parent_theme_file_uri('style.css'),
 array(),
 wp_get_theme(
 get_template()
 )->get('Version')
 );
}

이 코드는 부모 테마의 style.css를 불러오는 예시입니다. 부모 테마가 이미 자신의 CSS를 로드하는 구조라면 추가해서는 안 됩니다.

또한 위 두 예시를 무조건 한 파일에 모두 붙여 넣는 방식은 피해야 합니다. 부모 테마의 기존 로딩 구조에 맞는 코드만 선택해야 합니다.

④ CSS 로딩 순서는 브라우저에서 확인

자식 테마의 CSS가 로드되었더라도 부모 테마의 CSS보다 먼저 적용되면 나중에 로드되는 규칙 때문에 변경 내용이 덮어써질 수 있습니다.

브라우저 개발자 도구의 Network 및 Styles 탭에서 실제 스타일시트 로딩과 우선순위를 확인하세요.

필요한 경우 부모 스타일의 등록 핸들을 정확하게 확인한 뒤 wp_enqueue_style()의 의존성 배열로 로딩 순서를 지정할 수 있습니다.

⑤ functions.php를 부모 파일과 똑같이 복사하면 안 됩니다

자식 테마의 functions.php는 부모 테마의 같은 파일을 대체하지 않습니다.

자식 functions.php가 먼저 로드되고 부모 functions.php도 이어서 로드됩니다.

부모 파일의 함수를 그대로 복사하면 동일한 함수명이 두 번 선언되어 PHP 치명적 오류가 발생할 수 있습니다.

새로운 함수에는 my_site_child_처럼 고유한 접두어를 붙여 이름 충돌 위험을 줄이세요.

⑥ 블록 테마는 theme.json 설정을 우선 검토

Twenty Twenty-Four 같은 블록 테마는 theme.json을 통해 전역 스타일과 설정을 관리합니다.

이런 테마에서는 전통적인 CSS enqueue 방식이 항상 필요한 것은 아니므로 사이트 편집기와 theme.json을 함께 검토해야 합니다.

4. 워드프레스 자식 테마 설치·활성화 8단계

필수 파일을 준비했다면 바로 운영 사이트에서 활성화하기보다 백업과 테스트 환경을 먼저 마련하세요.

① ZIP 파일로 설치하는 방법

자식 테마 폴더를 ZIP 파일로 압축한 뒤 워드프레스 관리자에서 다음 경로로 이동합니다.

ZIP 내부에 style.css가 들어 있는 자식 테마 폴더가 올바르게 포함되어 있어야 합니다.

② SFTP로 설치하는 방법

호스팅 계정의 SFTP에 연결해 wp-content/themes/my-site-child/ 폴더를 업로드합니다.

서버의 파일 권한과 소유권이 잘못되어 워드프레스가 파일을 읽지 못하는 상황이 생기지 않도록 확인합니다.

③ 부모 테마는 삭제하면 안 됩니다

자식 테마가 활성화되어 있더라도 부모 테마는 설치된 상태로 유지되어야 합니다.

부모 테마가 없어지면 자식 테마가 상속받을 템플릿과 기능을 찾지 못해 사이트 표시 문제가 발생할 수 있습니다.

④ 활성화 후 반드시 확인할 화면

• 홈페이지 첫 화면과 헤더·푸터
• 개별 글과 페이지
• 카테고리 및 검색 결과 페이지
• 메뉴·위젯·사이드바와 모바일 화면
• 사이트 편집기에서 수정한 템플릿
• 캐시를 지운 후의 CSS 적용 상태

⑤ 기존 테마에서 설정이 달라질 수 있습니다

부모 테마에서 자식 테마로 활성 테마를 전환하면 일부 테마별 설정, 메뉴 위치나 위젯 구성이 다르게 표시될 수 있습니다.

특히 사이트 편집기의 사용자 정의 템플릿과 글로벌 스타일은 데이터베이스에 저장될 수 있으므로 활성화 전후에 실제 화면을 비교해야 합니다.

5. 템플릿·theme.json·사용자 정의 코드 안전하게 관리하기

자식 테마를 만들었다면 다음 단계는 어떤 파일을 자식 테마에 넣고 어떤 코드는 별도 플러그인으로 관리할지 정하는 것입니다.

코드를 모두 functions.php에 넣기보다는 역할별로 분리하면 오류를 추적하거나 수정 사항을 되돌리기 쉬워집니다.

① 템플릿 파일은 같은 경로와 이름으로 재정의

워드프레스 공식 개발자 문서에 따르면 자식 테마에 부모 테마의 템플릿과 동일한 상대 경로·파일명의 파일을 작성하면 해당 템플릿을 재정의할 수 있습니다.

클래식 테마에서는 single.php, page.php 같은 PHP 템플릿을 주로 사용합니다.

예를 들어 부모 테마의 single.php 구조를 수정하려면 해당 파일을 자식 테마로 복사한 뒤 필요한 부분만 변경할 수 있습니다.

다만 부모 테마 업데이트 때 템플릿 구조가 크게 달라지면 기존에 복사해 둔 자식 템플릿과 새로운 부모 기능 사이에 호환 문제가 발생할 수 있습니다.

② 블록 테마의 템플릿 구조

블록 테마는 일반적으로 templates/와 parts/ 폴더의 HTML 파일을 사용합니다.

my-site-child/
├── style.css
├── functions.php
├── theme.json
├── templates/
│ └── single.html
└── parts/
 └── footer.html

위 구조는 가능한 파일 구성을 보여주는 예시입니다. 실제 부모 테마의 구조와 수정 목적에 따라 필요한 파일만 만들면 됩니다.

특히 사이트 편집기에서 저장한 사용자 정의 템플릿은 데이터베이스에 저장되고 파일 기반 자식 템플릿보다 우선 적용될 수 있으므로 코드 수정 결과가 보이지 않을 때 함께 확인해야 합니다.

③ 자식 테마의 theme.json 사용

theme.json은 블록 테마에서 색상, 타이포그래피, 간격과 편집기 설정 등을 정의하는 데 사용하는 파일입니다.

자식 테마에 theme.json을 작성하면 부모 테마의 기존 설정을 활용하면서 필요한 항목을 재정의할 수 있습니다.

예를 들어 다음과 같은 설정을 자식 테마에 추가할 수 있습니다.

{
 "$schema": "https://schemas.wp.org/wp/6.6/theme.json",
 "version": 3,
 "settings": {
 "appearanceTools": true
 },
 "styles": {
 "elements": {
 "link": {
 "color": {
 "text": "#0d4f3c"
 }
 }
 }
 }
}

위 예시는 링크 색상을 설정하는 방법을 보여줍니다. 실제 사용 중인 워드프레스 버전과 부모 테마의 theme.json 설정을 확인한 후 적용해야 합니다.

워드프레스의 스타일 설정은 기본값, 부모 테마, 자식 테마, 사이트 편집기에서 저장한 사용자 설정 순으로 우선순위가 적용될 수 있습니다.

따라서 자식 theme.json에 설정했는데도 다른 스타일이 표시된다면 사이트 편집기에서 저장한 사용자 정의 스타일을 확인하세요.

④ 사이트 편집기에서 저장한 변경 사항도 백업 필요

블록 테마의 사이트 편집기에서 수정한 헤더, 푸터, 템플릿과 전역 스타일은 데이터베이스에 저장될 수 있습니다.

자식 테마 파일만 백업하면 이러한 사용자 정의 변경 사항까지 모두 보존되는 것은 아닙니다.

따라서 파일 백업과 함께 데이터베이스도 백업해야 합니다.

⑤ CSS 파일과 PHP 기능은 분리하기

레이아웃이나 디자인 수정은 style.css 또는 블록 테마의 theme.json에 넣고, 테마 동작과 관련된 PHP 코드는 자식 테마의 functions.php에서 관리할 수 있습니다.

여러 기능을 추가한다면 inc/ 같은 폴더로 PHP 파일을 분리해 관리하는 것도 방법입니다.

⑥ 자식 테마의 파일 경로 참조하기

자식 테마에서 이미지를 불러오거나 PHP 파일을 포함할 때에는 경로를 직접 문자열로 작성하는 것보다 워드프레스가 제공하는 함수를 사용하는 것이 안전합니다.

특히 자식 테마 안에만 있는 파일이라면 get_stylesheet_directory()와 get_stylesheet_directory_uri()를 사용할 수 있습니다.

부모 테마의 실제 파일을 가리켜야 할 경우에는 get_template_directory() 또는 get_parent_theme_file_uri()를 활용할 수 있습니다.

// 자식 테마 안의 PHP 파일
require_once get_stylesheet_directory()
 . '/inc/custom-layout.php';

// 자식 테마 안의 이미지 URL
$image_url = get_stylesheet_directory_uri()
 . '/assets/images/brand-mark.png';

위 코드는 functions.php 내부에 사용하는 예시입니다. 실제 파일이 존재하는지 먼저 확인해야 하며, 존재하지 않는 PHP 파일을 require_once로 불러오면 치명적 오류가 발생할 수 있습니다.

⑦ 테마와 관계없는 코드는 별도 플러그인으로

예를 들어 회원 권한 관리, 사용자 정의 게시글 유형, 외부 API 연동과 같은 기능은 테마를 변경해도 계속 유지되어야 할 수 있습니다.

이 경우에는 자식 테마 대신 별도 플러그인이나 사이트 전용 기능 플러그인으로 관리하는 것이 적절합니다.

⑧ Git으로 사용자 정의 코드 변경 이력 관리

자식 테마 폴더를 Git 저장소로 관리하면 CSS와 PHP 수정 내용을 비교하고 문제가 있는 변경 사항을 이전 버전으로 되돌리기 편리합니다.

단, API 키와 비밀번호 같은 비밀 정보는 Git 저장소에 올리지 않아야 합니다. 공개 저장소라면 설정 파일에 민감 정보가 포함되지 않았는지 반드시 확인하세요.

6. 자식 테마 오류·스타일 깨짐·업데이트 충돌 해결법

자식 테마 활성화 후 문제가 생겼다면 무작정 코드를 추가하거나 부모 테마 파일을 수정하기 전에 오류 증상부터 구분해야 합니다.

① ‘부모 테마가 없습니다’ 오류

자식 테마의 Template 값이 부모 폴더명과 다르거나 부모 테마가 설치되지 않은 경우 발생할 수 있습니다.

자식 테마의 style.css를 열어 다음 항목을 확인하세요.

부모 테마가 없으면 공식 배포처에서 정상 버전을 설치하고, 실제 디렉터리 이름을 확인하세요.

② 자식 테마를 활성화했더니 디자인이 깨지는 경우

부모 테마 스타일시트가 로드되지 않았거나 자식 CSS가 예상한 순서대로 적용되지 않았을 가능성이 있습니다.

브라우저 개발자 도구에서 CSS 파일 요청 상태를 확인하고, 부모 테마가 어떤 방식으로 스타일을 로드하는지 점검하세요.

블록 테마라면 theme.json과 사이트 편집기에서 저장한 사용자 정의 스타일도 확인해야 합니다.

③ functions.php를 수정한 뒤 하얀 화면이 나오는 경우

PHP 문법 오류, 중복 함수 선언, 존재하지 않는 파일을 불러오는 코드 등이 원인일 수 있습니다.

사이트에 접속할 수 없으면 SFTP 또는 호스팅 파일 관리자를 이용해 방금 추가한 자식 테마의 문제 코드를 제거하거나 이전 정상 파일로 복원하세요.

복구하기 전에는 변경 파일을 따로 보관하여 어떤 코드가 오류를 발생시켰는지 비교할 수 있도록 하는 것이 좋습니다.

④ 부모 functions.php를 복사해서 중복 오류가 발생한 경우

자식 테마의 functions.php는 부모 파일을 대체하는 것이 아니라 추가로 실행됩니다.

같은 함수를 그대로 선언하면 치명적 오류가 발생할 수 있으므로 복사한 내용을 제거하고 필요한 부분만 고유한 함수명과 훅을 이용해 구현하세요.

⑤ 자식 CSS를 수정해도 화면이 달라지지 않는 경우

캐시가 이전 스타일을 제공하거나 자식 CSS가 로드되지 않는 경우일 수 있습니다.

워드프레스 캐시 플러그인, CDN 캐시, 브라우저 캐시를 확인하고 개발자 도구로 실제 적용 중인 CSS 파일과 규칙의 우선순위를 점검하세요.

CSS 선택자가 부모 테마에서 바뀌었는지도 확인해야 합니다.

⑥ 부모 테마 업데이트 후 일부 기능만 고장 난 경우

자식 테마에 복사해 둔 템플릿이 부모 테마의 새로운 구조와 호환되지 않을 수 있습니다.

부모 테마의 변경 기록을 확인하고, 자식 테마의 템플릿과 최신 부모 템플릿을 비교하여 필요한 변경을 반영하세요.

부모 테마 업데이트 이전의 스테이징 환경이나 백업이 있다면 비교·복구가 훨씬 편리합니다.

⑦ 블록 테마에서 수정한 템플릿이 적용되지 않는 경우

사이트 편집기에서 사용자 정의 템플릿을 저장했다면 데이터베이스에 저장된 내용이 자식 테마 파일보다 우선 적용될 수 있습니다.

사이트 편집기의 템플릿 관리 화면에서 사용자 정의 상태를 확인하고, 기존 설정을 보존할지 초기화할지 신중하게 판단하세요.

⑧ 디버그 로그로 문제 분석하기

개발 또는 스테이징 환경에서는 워드프레스 디버그 기능을 사용해 PHP 오류를 기록할 수 있습니다.

예를 들어 wp-config.php에서 다음과 같이 설정할 수 있습니다.

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

실제 설정 시에는 wp-config.php에 같은 상수를 중복 정의하지 않아야 합니다.

기본 설정에서는 로그가 wp-content/debug.log에 기록될 수 있습니다. 이 파일에는 서버 경로나 내부 정보가 포함될 수 있으므로 외부 접근을 차단해야 합니다.

운영 사이트에서는 디버그 기능을 상시 활성화하기보다 문제 분석 후 비활성화하거나 적절한 로그 관리 정책을 적용하세요.

7. 워드프레스 자식 테마 FAQ 10가지

8. 워드프레스 자식 테마 코드 안전 관리 최종 체크리스트

부모 테마 업데이트에서 사용자 정의 코드를 보호하고 오류를 줄이려면 아래 항목을 확인하세요.

워드프레스 사이트에서 테마를 안전하게 수정하려면 부모 테마의 원본 코드를 직접 수정하지 않고 자식 테마를 생성하는 방법을 활용할 수 있습니다. 먼저 wp-content/themes에 자식 테마 폴더를 만들고 style.css에 Theme Name과 정확한 부모 폴더명인 Template을 지정합니다. 그런 다음 부모 테마가 실제로 어떤 CSS 파일을 불러오는지 확인하고 필요한 경우에만 자식 테마의 functions.php에서 스타일시트를 연결합니다. 부모의 functions.php를 통째로 복사하면 함수 중복 오류가 발생할 수 있으므로 필요한 코드만 고유한 이름으로 작성해야 합니다. 클래식 테마에서는 PHP 템플릿을, 블록 테마에서는 theme.json과 HTML 템플릿을 활용할 수 있지만 사용자가 사이트 편집기에 저장한 설정의 우선순위도 함께 고려해야 합니다. 자식 테마를 사용하면 부모 테마 업데이트로 사용자 정의 파일이 덮어써지는 위험을 줄일 수 있으나 호환성 오류까지 자동으로 방지하는 것은 아닙니다. 따라서 운영 사이트에서는 파일·데이터베이스 백업, 스테이징 테스트, 코드 이력 관리와 업데이트 후 화면 점검을 함께 수행하는 것이 좋습니다. 안전한 워드프레스 코드 관리의 핵심은 부모 테마 원본을 보존하고, 수정 내용을 자식 테마와 적절한 플러그인에 분리하며, 언제든 이전 상태로 복구할 수 있도록 준비하는 것입니다.