워드프레스 디버그 완벽 가이드 — WP_DEBUG부터 Query Monitor까지

워드프레스에서 에러가 발생했을 때 가장 중요한 것은 정확한 오류 원인을 파악하는 것입니다. 원인을 모른 채 해결책만 시도하면 시간이 낭비되고 문제가 악화될 수 있습니다. 이 가이드에서는 워드프레스 에러 진단에 사용하는 모든 디버그 방법을 단계별로 안내합니다.

이 글은 워드프레스 에러 해결 완벽 가이드와 연계한 심층 가이드입니다.

목차

• 1. 디버그란 무엇이고 왜 필요한가?
• 2. WP_DEBUG — 기본 디버그 모드
• 3. debug.log 파일 분석 방법
• 4. Query Monitor 플러그인 활용
• 5. 사이트 상태(Site Health) 도구
• 6. 플러그인·테마 충돌 디버그
• 7. 브라우저 개발자 도구 활용
• 8. 서버 에러 로그 확인 (카페24)
• 9. 고급 디버그 기법
• 10. 자주 묻는 질문 (FAQ)

1. 디버그란 무엇이고 왜 필요한가?

디버그(Debug)는 소프트웨어의 오류(버그)를 찾아내고 제거하는 과정입니다. 워드프레스에서 에러가 발생하면 단순히 “에러가 났다”는 사실만으로는 원인을 찾기 어렵습니다. 디버그 도구를 사용하면 정확히 어느 파일의 몇 번째 줄에서 무슨 오류가 발생했는지를 알 수 있어 빠른 해결이 가능합니다.

워드프레스 디버그 도구 전체 목록

2. WP_DEBUG — 기본 디버그 모드

WP_DEBUG는 워드프레스에 내장된 가장 기본적인 디버그 시스템입니다. wp-config.php 파일에 상수 값을 설정하여 동작합니다.

WP_DEBUG 설정 방법

카페24 파일 관리자 또는 FTP로 WordPress 루트의 wp-config.php 파일을 열고, /* That's all, stop editing! */ 줄 바로 위에 아래 코드를 추가합니다.

// ===== 디버그 설정 시작 =====
define('WP_DEBUG', true);           // 디버그 모드 활성화
define('WP_DEBUG_LOG', true);       // debug.log 파일에 오류 기록
define('WP_DEBUG_DISPLAY', false);  // 화면에 오류 표시 안 함 (운영 환경 필수)
define('SCRIPT_DEBUG', true);       // 압축되지 않은 JS/CSS 로드
// ===== 디버그 설정 끝 =====

각 상수의 역할

WP_DEBUG

• true: PHP 오류, 경고, 알림을 모두 감지합니다.
• false (기본값): 오류를 감지하지 않습니다.
• 운영 사이트에서는 false로 유지해야 합니다.

WP_DEBUG_LOG

• true: 발생한 모든 오류를 /wp-content/debug.log 파일에 기록합니다.
• WP_DEBUG_DISPLAY가 false여도 로그 파일에는 계속 기록됩니다.
• 파일 경로를 직접 지정할 수도 있습니다: define('WP_DEBUG_LOG', '/home/user/logs/debug.log');

WP_DEBUG_DISPLAY

• true: 오류 메시지를 화면(브라우저)에 직접 표시합니다.
• false (권장): 화면에는 표시하지 않고 log 파일에만 기록합니다.
• 운영 사이트에서 true로 설정하면 방문자에게 오류 코드가 노출되어 보안에 위험합니다.

SCRIPT_DEBUG

• true: 워드프레스가 압축·최소화된 JS/CSS 대신 원본 파일을 로드합니다.
• JavaScript 오류 디버그 시 유용합니다.

디버그 완료 후 반드시 비활성화

디버그 작업이 끝나면 반드시 아래와 같이 변경하시기 바랍니다.

define('WP_DEBUG', false);
// WP_DEBUG_LOG, WP_DEBUG_DISPLAY 줄은 삭제하거나 주석 처리

3. debug.log 파일 분석 방법

debug.log는 워드프레스가 감지한 PHP 오류를 시간순으로 기록하는 텍스트 파일입니다. WP_DEBUG와 WP_DEBUG_LOG가 모두 true일 때 /wp-content/debug.log 경로에 자동 생성됩니다.

debug.log 파일 열기

1. 카페24 파일 관리자 → /www/wp-content/ 폴더
2. debug.log 파일을 클릭하여 내용 확인 (또는 FTP로 다운로드)
3. 파일이 보이지 않으면 [숨김 파일 보기]를 활성화합니다.

오류 유형별 의미

debug.log에서 원인을 빠르게 찾는 방법

1. “Fatal error” 키워드로 검색합니다. (Ctrl+F 또는 Cmd+F)
2. 오류 메시지에서 파일 경로를 확인합니다. 예: /wp-content/plugins/plugin-name/class.php on line 123
3. 경로에 plugins/플러그인명이 있으면 해당 플러그인이 원인입니다.
4. 경로에 themes/테마명이 있으면 테마가 원인입니다.

debug.log 주요 오류 패턴

# 플러그인 함수 충돌 (두 플러그인이 같은 함수명 사용)
Fatal error: Cannot redeclare function_name() ... in /plugins/plugin-a/file.php

# 정의되지 않은 함수 호출 (플러그인 누락 또는 비활성화)
Fatal error: Call to undefined function plugin_function() in /plugins/plugin-b/file.php

# 메모리 부족
Fatal error: Allowed memory size of 134217728 bytes exhausted

# PHP 버전 비호환
Fatal error: Uncaught TypeError: Argument must be of type string, bool given

4. Query Monitor 플러그인 활용

Query Monitor는 워드프레스의 성능과 오류를 실시간으로 분석하는 개발자용 플러그인입니다. 데이터베이스 쿼리, PHP 오류, HTTP API 호출, 훅(Hook) 등 매우 상세한 정보를 관리자 바에서 바로 확인할 수 있습니다.

Query Monitor 설치 방법

1. 워드프레스 관리자 → [플러그인] → [새 플러그인 추가]
2. “Query Monitor” 검색 후 설치 및 활성화
3. 사이트에 접속하면 관리자 바에 “0.43s / 42 queries / 8.5 MB” 형태의 통계가 표시됩니다.

Query Monitor 주요 패널 설명

Queries (데이터베이스 쿼리)

• 페이지 로드 시 실행된 모든 SQL 쿼리를 표시합니다.
• 실행 시간이 긴 쿼리(느린 쿼리)는 붉은색으로 강조됩니다.
• Caller 컬럼에서 해당 쿼리를 발생시킨 플러그인/테마를 확인합니다.
• 0.05초 이상 걸리는 쿼리는 최적화 대상입니다.

PHP Errors (PHP 오류)

• debug.log 없이도 PHP 오류를 실시간으로 확인할 수 있습니다.
• Fatal, Warning, Notice, Deprecated 등 모든 오류 유형을 표시합니다.

Hooks (훅)

• 페이지 로드 시 실행된 모든 WordPress 훅(action/filter)을 표시합니다.
• 특정 훅이 예상대로 실행되는지 확인할 때 유용합니다.

HTTP API Calls

• 외부 API 호출(결제 게이트웨이, 지도, 소셜 로그인 등)을 모니터링합니다.
• 느린 외부 API 응답이 504 에러를 유발하는지 확인할 수 있습니다.

Request (요청 정보)

• 현재 페이지의 WordPress 쿼리 변수, 매칭된 rewrite rule 등을 표시합니다.
• 404 에러나 퍼머링크 문제 디버그에 유용합니다.

5. 사이트 상태(Site Health) 도구

워드프레스 내장 사이트 상태 도구는 서버 환경, 플러그인 호환성, 보안 설정 등을 자동으로 점검하고 개선 방법을 안내합니다.

접근 방법

워드프레스 관리자 → [도구] → [사이트 상태]

주요 점검 항목

[상태] 탭

• 치명적 문제 (빨강): 즉시 해결이 필요한 항목입니다.
• 권장 사항 (노랑): 개선하면 좋은 항목입니다.
• 통과 (녹색): 정상 상태인 항목입니다.

[정보] 탭

• PHP 버전, 메모리 한도, 최대 실행 시간 등 서버 정보
• 활성화된 플러그인과 테마 목록
• 데이터베이스 정보
• 파일 권한 상태

사이트 상태 정보는 고객센터나 개발자에게 문제를 보고할 때도 유용합니다. [정보 복사] 버튼으로 전체 환경 정보를 클립보드에 복사할 수 있습니다.

6. 플러그인·테마 충돌 디버그

워드프레스 에러의 상당수는 플러그인 또는 테마 간의 충돌에서 발생합니다. 체계적으로 원인을 격리하는 방법을 안내합니다.

플러그인 비활성화 테스트 (이분 탐색법)

활성화된 플러그인이 많을 때 빠르게 원인을 찾는 방법입니다.

1. 활성화된 플러그인의 절반을 비활성화합니다.
2. 에러가 해결되면 방금 비활성화한 플러그인 중에 원인이 있습니다.
3. 해당 그룹을 다시 절반씩 나누어 반복합니다.
4. 원인 플러그인을 찾을 때까지 반복합니다.

관리자 화면 접속이 불가능할 때 (FTP 사용)

1. 카페24 파일 관리자 → /www/wp-content/
2. plugins 폴더명을 plugins_disabled로 변경 → 전체 비활성화
3. 문제 해결 시 폴더명 원래대로 복구 → 플러그인을 하나씩 활성화하여 원인 탐색

기본 테마로 전환하여 테마 원인 확인

1. 관리자가 열린다면: 외모 → 테마 → Twenty Twenty-Four 활성화
2. 관리자가 열리지 않는다면: FTP로 현재 테마 폴더명 변경
3. 에러 해결 시 테마가 원인 → 테마 업데이트 또는 재설치

7. 브라우저 개발자 도구 활용

PHP 오류가 아닌 JavaScript 오류, CSS 깨짐, 느린 리소스 로딩 등은 브라우저 개발자 도구에서 확인합니다.

개발자 도구 열기

• Chrome/Edge: F12 또는 Ctrl+Shift+I (Mac: Cmd+Option+I)
• Firefox: F12 또는 Ctrl+Shift+I

주요 탭별 활용법

Console 탭

• JavaScript 오류를 확인합니다.
• 빨간색 오류 메시지가 있으면 해당 스크립트 파일과 줄 번호를 확인합니다.
• 워드프레스 관리자 화면이 깨지거나 JS 기능이 동작하지 않을 때 필수 확인 항목입니다.

Network 탭

• 페이지 로드 시 모든 HTTP 요청과 응답 코드를 확인합니다.
• 404(빨강), 500, 502, 503 등 에러 응답이 있는 요청을 찾습니다.
• 느리게 로드되는 리소스를 파악합니다.

Application 탭

• 캐시, 쿠키, 로컬 스토리지 데이터를 확인하고 삭제할 수 있습니다.
• 캐시 문제로 의심될 때 모든 캐시를 삭제하고 테스트합니다.

8. 서버 에러 로그 확인 (카페24)

PHP Fatal Error가 WordPress가 감지하기 전에 서버 레벨에서 발생하는 경우 WordPress의 debug.log에 기록되지 않을 수 있습니다. 이때는 서버 에러 로그를 직접 확인합니다.

카페24에서 에러 로그 확인 방법

1. 카페24 호스팅 관리자 → [나의 서비스 관리] → [호스팅 관리]
2. [로그 관리] 또는 [에러 로그] 메뉴 클릭
3. 날짜와 시간이 에러 발생 시점과 일치하는 항목을 찾습니다.

FTP로 직접 에러 로그 확인

카페24의 에러 로그는 일반적으로 아래 경로에 있습니다.

# 카페24 에러 로그 일반 경로
/www/logs/error.log
/logs/php-error.log

9. 고급 디버그 기법

var_dump와 error_log를 활용한 임시 디버그

특정 변수의 값을 확인하거나 코드 실행 흐름을 추적할 때 사용합니다.

// debug.log에 변수 내용 기록
error_log('변수 확인: ' . print_r($variable, true));

// 배열 또는 객체 전체 내용 확인
error_log(var_export($array, true));

// 실행 시점 확인
error_log('이 코드가 실행됨 — ' . date('Y-m-d H:i:s'));

wp_die()로 중간 값 확인

// 코드 실행을 중단하고 값 출력
wp_die('
' . print_r($variable, true) . '
');

주의: 이 방법은 개발 환경에서만 사용하고, 운영 환경에서는 반드시 제거해야 합니다.

SAVEQUERIES로 DB 쿼리 추적

// wp-config.php에 추가
define('SAVEQUERIES', true);

// 코드에서 사용
global $wpdb;
var_dump($wpdb->queries);  // 모든 실행된 쿼리 확인

Xdebug 연동 (고급)

로컬 개발 환경(Local by Flywheel, XAMPP 등)에서 PHP Xdebug를 PHPStorm 또는 VS Code와 연동하면 브레이크포인트를 설정하여 코드를 단계별로 실행하며 디버그할 수 있습니다. 카페24 등 공유 호스팅에서는 직접 사용이 제한적입니다.

디버그 전용 플러그인 목록

• Query Monitor: 가장 강력한 무료 디버그 플러그인
• Debug Bar: 관리자 바에 디버그 정보 추가
• WP Crontrol: WordPress cron 작업 모니터링
• Health Check & Troubleshooting: 관리자만 디버그 모드 적용 가능

10. 자주 묻는 질문 (FAQ)

Q. WP_DEBUG를 활성화해도 debug.log 파일이 생성되지 않아요.

WP_DEBUG_LOG를 true로 설정했는지 확인하고, wp-content 폴더에 쓰기 권한(755)이 있는지 확인하시기 바랍니다. 또는 wp-content 폴더 안에 빈 debug.log 파일을 미리 만들고 권한을 644로 설정하면 됩니다.

Q. 디버그가 끝난 후 WP_DEBUG를 다시 끄는 방법은?

wp-config.php에서 define('WP_DEBUG', true)를 define('WP_DEBUG', false)로 변경하면 됩니다. 운영 환경에서는 반드시 디버그 모드를 비활성화해야 합니다. WP_DEBUG_DISPLAY를 false로 유지하면 화면에 오류 메시지가 노출되지 않습니다.

Q. Query Monitor와 Debug Bar 중 어느 것을 사용해야 하나요?

Query Monitor를 권장합니다. Debug Bar보다 훨씬 많은 정보(DB 쿼리, 훅, REST API, 블록 에디터 데이터 등)를 제공하며 인터페이스가 더 직관적입니다. 두 플러그인 모두 무료로 사용할 수 있습니다.

Q. 운영 중인 사이트에서 디버그 모드를 켜도 되나요?

WP_DEBUG_DISPLAY를 반드시 false로 설정한 상태에서만 켜시기 바랍니다. 이 설정을 지키면 방문자 화면에 오류 메시지가 노출되지 않고 debug.log에만 기록됩니다. 디버그 완료 후에는 WP_DEBUG를 false로 되돌리는 것을 잊지 마시기 바랍니다.

Q. debug.log 파일이 너무 커져서 관리가 어려워요.

디버그 작업 후 WP_DEBUG를 다시 false로 변경하고 debug.log 파일을 삭제하면 됩니다. 또는 WP Crontrol 플러그인으로 정기적으로 로그 파일을 정리하도록 설정할 수 있습니다.

정리 — 워드프레스 디버그, 이렇게 진행하세요

워드프레스 디버그의 기본 순서는 아래와 같습니다.

1. WP_DEBUG 활성화 → debug.log에서 Fatal error 확인
2. 오류 메시지의 파일 경로로 원인 플러그인/테마 파악
3. 해당 플러그인/테마 비활성화로 확인
4. 결원이 특정되지 않으면 이분 탐색법으로 플러그인 범위 좁히기
5. Query Monitor로 DB 쿼리·성능 문제 추가 점검
6. 브라우저 DevTools Console로 JS 오류 확인
7. 해결 후 WP_DEBUG 비활성화

에러 코드별 구체적인 해결 방법은 아래 가이드를 참고하시기 바랍니다.

• 워드프레스 에러 해결 완벽 가이드 (전체 에러 총정리)
• 워드프레스 PHP Fatal Error 해결 가이드
• 워드프레스 500 Internal Server Error 해결 가이드