워드프레스 자식 테마 오류 해결 — 흰화면·CSS 깨짐·함수 충돌 즉시 고치는 법
✅ 핵심 답변
자식 테마 오류 해결 방법: 흰화면은 자식 테마 폴더 이름 임시 변경으로 즉시 복구하고, CSS 깨짐은 추가CSS 재입력으로, 함수 중복 오류는 부모 테마 functions.php에서 커스텀 코드를 삭제하면 해결됩니다.
자식 테마를 활성화하는 순간 흰화면이 떴다면, 당황하지 마세요 — 90% 이상은 단순한 설정 실수입니다. 워드프레스 자식 테마 오류는 대부분 흰화면(WSOD), CSS 레이아웃 깨짐, 함수 중복 충돌 세 가지로 나뉩니다. 각 증상마다 원인이 명확하게 다르고 해결 방법도 다릅니다.
이 글에서는 자식 테마 활성화 후 발생할 수 있는 3가지 주요 오류의 원인과 단계별 해결법, 그리고 재발 방지 체크리스트를 정리합니다.
📅 최종 업데이트: 2026년 04월 | ✍️ 정보 출처: WordPress 공식 문서 기준
1. 오류 유형 먼저 파악하기
증상으로 원인 찾기
자식 테마 활성화 후 나타나는 오류는 증상에 따라 원인이 다릅니다. 아래 표에서 내 증상을 먼저 찾고 해당 섹션으로 이동하세요. WordPress 공식 문서는 자식 테마 오류의 대부분이 파일 문법 오류, 함수 중복 정의, CSS 로드 순서 문제에서 발생한다고 명시합니다. (출처: WordPress 공식 개발자 문서)
| 증상 | 주요 원인 | 해당 섹션 |
|---|---|---|
| 사이트 전체 흰 화면 | PHP 문법 오류, 메모리 초과 | 섹션 2 |
| 레이아웃·버튼 CSS 깨짐 | 추가CSS 초기화, enqueue 오류 | 섹션 3 |
| “cannot redeclare” 에러 | 부모·자식 functions.php 함수 중복 | 섹션 4 |
| 테마 목록에 자식 테마 안 보임 | style.css 헤더 오류, 폴더명 오류 | 섹션 5 |
- 흰화면(WSOD): 사이트 접근 자체가 불가한 가장 심각한 상태
- CSS 깨짐: 사이트는 열리지만 레이아웃·스타일이 비정상
- 함수 오류: 특정 기능 동작 불가 또는 PHP 에러 메시지 표시
2. 흰화면(WSOD) 즉시 복구 방법
접근 불가 상태 탈출법
자식 테마를 활성화한 후 사이트 전체가 흰 화면으로 바뀌는 현상을 WSOD(White Screen of Death)라고 합니다. 대시보드 접근도 불가하다면 파일 매니저에서 자식 테마 폴더 이름을 바꾸는 것이 가장 빠른 응급 복구법입니다. WordPress 디버그 커뮤니티에서도 이 방법을 WSOD 1순위 해결책으로 권장합니다. (출처: marketingbyali.com, 2023)
🚨 WSOD 응급 복구 체크리스트 (순서대로)
- ☐ 파일 매니저 → wp-content/themes/ 접속
- ☐ 자식 테마 폴더(예: generatepress-child) 이름을 generatepress-child-backup으로 변경
- ☐ 워드프레스가 자동으로 기본 테마로 전환 → 사이트 복구 확인
- ☐ 대시보드 → 외모 → 테마에서 부모 테마 활성화
- ☐ wp-config.php 파일 열기 → define(‘WP_DEBUG’, false); → true로 변경 저장
- ☐ 자식 테마 폴더 이름 원래대로 복구 후 활성화 → 오류 메시지 확인
- ☐ 오류 내용으로 functions.php 또는 다른 PHP 파일 문제 위치 파악
- ☐ 문제 파일 수정 후 WP_DEBUG 다시 false로 변경
- WP_DEBUG 활성화 코드:
define('WP_DEBUG', true); define('WP_DEBUG_LOG', true); - 오류 로그 위치: wp-content/debug.log
- 복구 후 반드시 WP_DEBUG를 false로 되돌릴 것 (보안상 운영 중 true 유지 금지)
3. CSS 깨짐 오류 해결하는 방법
스타일 복구 3단계
사이트는 열리지만 버튼·레이아웃·색상이 이상하게 보인다면 대부분 두 가지 이유입니다. 첫째, 추가CSS가 테마 전환으로 초기화된 경우이고, 둘째, functions.php의 enqueue 코드가 CSS 로드 순서를 망가뜨린 경우입니다. Reddit r/Wordpress 커뮤니티 분석에 따르면 추가CSS 초기화가 자식 테마 전환 후 CSS 손실의 주요 원인입니다. (출처: Reddit r/Wordpress, 2021)
✅ CSS 깨짐 진단 체크리스트
- ☐ 시크릿 창(Ctrl+Shift+N)에서도 같은 문제인가? → YES면 CSS 자체 문제 / NO면 캐시 문제
- ☐ 대시보드 → 추가CSS가 비어있는가? → YES면 추가CSS 초기화 원인
- ☐ functions.php enqueue 코드에 generate-style 의존성 설정이 되어 있는가?
- ☐ 자식 테마 폴더에 불필요하게 복사된 PHP 파일이 있는가?
- ☐ 부모 테마 활성화 시 CSS가 정상인가? → YES면 자식 테마 파일 문제
- 추가CSS 초기화 → 부모 테마에서 복사해 둔 CSS를 자식 테마 추가CSS에 붙여넣기
- enqueue 오류 → functions.php enqueue 코드를 아래 올바른 형태로 교체
- 불필요한 PHP 파일 → 수정하지 않은 파일은 자식 폴더에서 삭제
4. 함수 중복 오류(cannot redeclare) 해결법
중복 함수 제거가 핵심
워드프레스는 자식 테마와 부모 테마의 functions.php를 모두 실행합니다. 만약 동일한 함수명이 양쪽에 모두 존재하면 “Fatal error: Cannot redeclare function_name()” 오류가 발생합니다. 해결 원칙은 단순합니다 — 커스텀 코드는 자식 functions.php에만 두고, 부모 functions.php에서는 완전히 삭제해야 합니다.
⚠️ 함수 중복 오류 해결 체크리스트
- ☐ 오류 메시지에서 중복된 함수명 확인 (예: “Cannot redeclare get_adjacent_posts”)
- ☐ 부모 테마 generatepress/functions.php 열기
- ☐ 해당 함수명 검색 → 부모 파일에서 해당 함수 전체 삭제
- ☐ 자식 테마 functions.php에 해당 함수가 남아있는지 확인
- ☐ 부모 파일 저장 후 사이트 새로고침으로 오류 해소 확인
- ☐ GeneratePress 원본 코드(generate_setup, GENERATE_VERSION 등)는 절대 자식에 복사하지 않음
- generate_setup, GENERATE_VERSION 같은 원본 코드를 자식에 넣으면 즉시 충돌 발생
- 자식 functions.php에는 커스텀 코드만, 부모 functions.php는 원본 상태 유지
- function_exists() 조건으로 감싸는 방법도 충돌 방지에 효과적
5. 오류 재발 방지 체크리스트
사전 예방이 최선
자식 테마 오류는 올바른 순서와 원칙만 지키면 대부분 예방할 수 있습니다. 아래 체크리스트는 자식 테마 생성·활성화·업데이트 단계별 사전 점검 목록입니다. 특히 부모 테마를 업데이트하기 전에는 자식 테마가 올바르게 활성화된 상태인지 반드시 확인하세요.
✅ 자식 테마 오류 예방 최종 체크리스트
📁 생성 단계
- ☐ style.css 상단 주석에 Theme Name과 Template 정확히 입력
- ☐ Template 값이 부모 테마 폴더명과 정확히 일치(generatepress)
- ☐ functions.php 인코딩이 UTF-8 BOM 없음으로 저장
⚡ 활성화 단계
- ☐ 활성화 전 부모 테마 추가CSS 메모장에 백업
- ☐ 부모 functions.php에서 커스텀 코드 삭제 완료 확인
- ☐ 활성화 직후 시크릿 창으로 전 페이지 정상 확인
- ☐ 추가CSS 자식 테마에 재입력 완료
🔄 업데이트 단계
- ☐ 자식 테마가 활성 상태인지 확인 후 부모 테마 업데이트
- ☐ 업데이트 후 시크릿 창으로 사이트 정상 여부 확인
- ☐ 업데이트로 부모 functions.php가 원복됐는지 확인
- 자식 테마는 한 번 올바르게 설정하면 이후 부모 테마 업데이트는 안전
- 정기적으로 자식 테마 폴더 내 파일 목록 점검 권장
- 테마 전체 백업은 UpdraftPlus 같은 플러그인 활용 권장
결론
워드프레스 자식 테마 오류의 90%는 흰화면·CSS 깨짐·함수 중복 세 가지이며, 각각 폴더 복구→디버그 확인, 추가CSS 재입력, 부모 함수 삭제로 해결한다. 오류가 발생해도 파일 매니저 접근만 가능하다면 폴더 이름 변경 하나로 즉시 사이트를 살릴 수 있습니다.
무엇보다 중요한 것은 사전 예방입니다. 추가CSS 백업, 부모 functions.php 원본 유지, 자식 테마 활성화 후 시크릿 창 확인 — 이 세 가지 습관만으로 대부분의 자식 테마 오류를 원천 차단할 수 있습니다. 백업 없이 진행하는 것이 가장 큰 실수임을 항상 기억하세요.
— 워드프레스 개발 및 트러블슈팅 전문가 관점
📚 기초
Q1. 자식 테마를 활성화하면 왜 흰화면이 나타나나요?
자식 테마의 PHP 파일(주로 functions.php)에 문법 오류가 있거나, 부모 테마와 함수명이 중복될 때 발생합니다. 파일 매니저에서 자식 테마 폴더 이름을 임시로 바꾸면 즉시 복구됩니다.
Q2. WP_DEBUG는 어디서 활성화하나요?
파일 매니저 또는 FTP로 wp-config.php 파일을 열고 define(‘WP_DEBUG’, false); 를 define(‘WP_DEBUG’, true);로 변경 후 저장하면 됩니다. 오류 확인 후 반드시 false로 되돌리세요.
Q3. 자식 테마 활성화 후 관리자 페이지도 접근이 안 되면 어떻게 하나요?
대시보드 접근이 불가하면 파일 매니저(호스팅 cPanel)로 직접 접속해 wp-content/themes/ 안의 자식 테마 폴더 이름을 변경하면 워드프레스가 자동으로 다른 테마로 전환하며 관리자 접근이 복구됩니다.
Q4. 테마 목록에 자식 테마가 안 보이는 이유는 무엇인가요?
style.css의 테마 헤더 주석에 오류가 있거나 Template 값이 부모 테마 폴더명과 다를 때 발생합니다. style.css를 열어 Template: generatepress가 정확히 입력돼 있는지 확인하세요.
Q5. 오류 로그는 어디서 볼 수 있나요?
WP_DEBUG와 WP_DEBUG_LOG를 모두 true로 설정하면 wp-content/debug.log 파일에 오류가 기록됩니다. 파일 매니저에서 해당 파일을 열어 오류 내용을 확인할 수 있습니다.
⚠️ 주의사항
Q6. WP_DEBUG를 운영 중인 사이트에 계속 켜두면 안 되나요?
네, 운영 중에는 반드시 false로 설정해야 합니다. true 상태에서는 오류 메시지가 방문자에게 그대로 노출되어 보안 취약점이 될 수 있습니다. 오류 확인 후 즉시 false로 되돌리세요.
Q7. 부모 테마 업데이트 후 사이트가 깨지는 이유는 무엇인가요?
자식 테마가 아닌 부모 테마가 활성화된 상태에서 업데이트하면 직접 수정한 부모 파일이 덮어쓰입니다. 반드시 자식 테마를 활성화한 상태에서 부모 테마를 업데이트해야 합니다.
Q8. 자식 테마 functions.php에 PHP 코드를 복사할 때 주의할 점은 무엇인가요?
워드(Word) 또는 한글 문서에서 복사할 경우 스마트 따옴표(“”)가 자동 변환돼 PHP 오류가 발생합니다. 반드시 메모장(Notepad) 또는 코드 에디터(VS Code)에서 복사해야 합니다.
Q9. 자식 테마 PHP 파일을 직접 편집기로 수정하다가 실수했을 때 복구 방법은?
편집 전 파일 내용을 메모장에 복사해 백업해 두는 습관이 중요합니다. 백업이 없다면 부모 테마의 동일 파일을 다시 자식 폴더에 복사하고 수정 내용을 재작업해야 합니다.
Q10. 자식 테마 오류를 예방하는 가장 확실한 방법은 무엇인가요?
활성화 전 추가CSS 백업, 자식 폴더에 수정한 파일만 복사, 부모 functions.php 원본 유지, 활성화 직후 시크릿 창으로 전 페이지 확인 — 이 네 가지 원칙을 지키면 대부분의 오류를 예방할 수 있습니다.