워드프레스 자식 테마 functions.php 이전 – 충돌 없이 안전하게

1. functions.php가 특수한 이유

유일하게 둘 다 실행되는 파일

워드프레스의 모든 템플릿 파일(header.php, single.php 등)은 자식에 있으면 부모 것을 완전히 무시합니다. 그러나 functions.php만은 예외로, 자식 functions.php가 먼저 실행되고 이어서 부모 functions.php가 실행됩니다. 이 때문에 같은 함수명이 양쪽에 존재하면 “함수 중복 선언” 치명적 오류가 발생합니다.(출처: WordPress 공식 문서)

• 일반 PHP 파일: 자식 있으면 부모 무시 (자식 단독 실행)
• functions.php: 자식 먼저 → 부모 나중 (둘 다 실행)
• 따라서 자식 functions.php에는 커스텀 코드만 있어야 함

2. 원본 코드 vs 커스텀 코드 구분하기

이 표로 한눈에 구분하세요

부모 functions.php를 열었을 때 어떤 코드가 원본이고 어떤 코드가 내가 추가한 것인지 구분이 어려울 수 있습니다. 아래 표를 참고해 명확히 구분하세요.

3. 자식 functions.php 올바른 구조

이 구조만 따르면 충돌 없습니다

자식 functions.php는 enqueue 코드 + 커스텀 코드로만 구성합니다. enqueue 코드는 부모 CSS를 올바른 순서로 로드하기 위한 필수 선언이며, 그 아래에 커스텀 코드를 붙여넣으면 됩니다. GeneratePress의 경우 generate-style이 부모 CSS 핸들명이므로 의존성으로 지정해야 합니다.

• GeneratePress 원본 코드(define, generate_setup, require) 절대 포함 금지
• 커스텀 코드는 require 구문 이후에 있던 코드만 복사

<?php
/**
 * 자식 테마 Functions
 */

// 자식 테마 스타일 로드 (필수)
add_action('wp_enqueue_scripts', 'gp_child_enqueue_styles');
function gp_child_enqueue_styles(){
    wp_enqueue_style(
        'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array('generate-style')
    );
}

// 여기 아래에 커스텀 코드만 붙여넣기
// (SNS 공유버튼, 쇼트코드, 관리자메뉴 등)

// 아래 코드들은 자식 functions.php에 넣으면 충돌 발생
define( 'GENERATE_VERSION', '3.3.1' );  // ❌
function generate_setup() { ... }       // ❌
require $theme_dir . '/inc/...';        // ❌

4. 부모 functions.php 원본 복원

커스텀 코드 삭제 후 저장

자식 functions.php에 커스텀 코드 이전이 완료되면 부모 functions.php에서 해당 코드를 삭제해야 합니다. 부모 파일을 열어 마지막 require 구문 이후에 있는 모든 커스텀 코드를 삭제하고 저장합니다. 삭제 후 파일 마지막 줄이 아래처럼 끝나면 정상입니다.

• 삭제 대상: require $theme_dir . ‘/inc/structure/search-modal.php’; 이후 모든 코드
• 삭제 후 마지막 줄: require $theme_dir . ‘/inc/structure/search-modal.php’;
• 삭제 완료 후 저장 → 사이트 정상 확인

5. 이전 후 이상 여부 확인

3가지 항목을 순서대로 확인하세요

커스텀 코드 이전이 완료되면 아래 순서로 정상 작동 여부를 확인합니다. 시크릿 창으로 확인하는 것이 캐시 오염 없이 실제 상태를 볼 수 있는 가장 정확한 방법입니다.

• ① 시크릿 창(Ctrl+Shift+N)으로 사이트 접속 → 디자인 정상 확인
• ② 커스텀 기능(SNS 버튼, 쇼트코드 등) 정상 작동 확인
• ③ 대시보드 → 외모 → 테마 파일 편집기에서 자식 functions.php 내용 최종 확인

결론