워드프레스를 운영하다 보면 다양한 기술적 문제를 마주할 때가 있습니다. 이때 문제의 근본 원인을 파악하려면 디버그 모드를 활성화하는 것이 유용합니다.
이 글에서는 디버그 모드의 정의와 활성화 방법, 오류 로그 확인 방법, 그리고 오류 메시지를 이해하는 방법을 단계별로 설명합니다.
디버그 모드란?
디버그 모드는 소프트웨어 개발 과정에서 오류를 찾아내고 수정하기 위해 사용하는 실행 모드입니다. 일반적인 모드와 달리, 프로그램의 실행 과정을 단계별로 추적하고 변수 값의 변화를 확인할 수 있습니다. 또한, 오류 발생 시점과 원인을 파악하는 데 필요한 다양한 정보를 제공합니다.
이 모드는 프로그램의 논리적 오류, 예외 처리 문제, 메모리 누수 등 여러 버그를 해결하는 데 필수적입니다. 이를 통해 프로그램의 안정성과 신뢰성을 높이는 중요한 역할을 합니다.
워드프레스의 디버그 모드는 PHP 오류, 경고, 알림을 확인하는 기능입니다. 기본 설정에서는 보안을 위해 디버그 모드가 비활성화되어 있어 문제의 원인을 정확히 파악하기 어렵습니다. 사이트에 오류가 발생하면 디버그 모드를 활성화해 원인을 찾아 해결할 수 있습니다.
디버그 모드 활성화 방법
워드프레스 사이트에 치명적인 문제가 발생할 경우 “이 웹사이트에 치명적인 오류가 있습니다. 워드프레스 장애복구에 관해 더 알아보기.” 오류가 표시됩니다.
경우에 따라 아무런 에러가 표시되지 않고 흰 화면이 표시되면서 접속이 안 되는 경우도 있습니다.
사이트 오류를 해결하기 위해서는 먼저 원인을 파악해야 합니다. 원인 파악의 첫 걸음인 오류 로그(Error Log)를 확인하는 것입니다.
오류 로그는 소프트웨어 시스템에서 발생하는 문제와 예외 상황을 기록하는 중요한 진단 도구입니다. 시스템의 동작 상태를 추적하고 장애 발생 시 근본 원인을 파악하는 데 핵심적인 역할을 합니다. 오류 로그는 일반적으로 DEBUG, INFO, WARN, ERROR, FATAL과 같은 심각도 레벨로 구분됩니다. 이를 통해 개발자와 시스템 관리자는 문제의 위치, 발생 시간, 상세 내용을 파악할 수 있습니다.
워드프레스에서는 디버그 모드를 활성화하여 오류 메시지를 확인할 수 있습니다.
워드프레스 사이트에서 디버그 모드 활성화하기
디버그 모드를 활성화하려면 FTP/SFTP에 접속하여 wp-config.php 파일에서 디버그 모드(WP_DEBUG)를 true으로 변경해야 합니다. 이 작업을 위해서는 FTP에 접속할 수 있어야 합니다.
예를 들어, PC에서 파일질라(FileZilla)를 사용하여 FTP에 접속하는 경우 워드프레스가 설치된 루트 폴더로 이동하여 wp-config.php 파일 위에 마우스를 올린 다음, 오른쪽 마우스 버튼을 누르고 보기/편집을 클릭합니다.
워드프레스 구성 파일에서 다음 라인을 찾도록 합니다.
define('WP_DEBUG', false);WP_DEBUG로 검색하여 위의 코드를 찾을 수 있습니다. 기본적으로 위의 라인과 같이 WP_DEBUG는 false로 설정되어 있습니다. false를 true로 변경합니다.
define('WP_DEBUG', true);디버그 모드를 활성화하면 사이트에 구체적인 오류 메시지가 표시될 수 있습니다.
위의 화면에서는 차일드 테마의 함수 파일(functions.php)에 your_function() 함수가 중복으로 정의되어 치명적인 오류가 발생하는 예를 보여줍니다. 이 경우 문제가 되는 함수를 삭제하면 사이트가 정상화됩니다.
wp-config.php 파일을 찾을 수 없는 경우 아래의 “부록: wp-config.php 파일 위치를 찾을 수 없는 경우” 부분을 참고하세요.
관리자 페이지에 접속이 가능한 경우 Error Log Monitor 플러그인을 사용하여 오류 로그 확인하기
사이트에는 접속할 수 없지만 관리자 페이지에는 접속이 가능한 경우에는 Error Log Monitor라는 플러그인을 설치하여 알림판에서 PHP 오류 로그를 확인하는 것도 가능합니다.
일반적으로 사이트에 심각한 오류가 발생하면 관리자 페이지에도 접속할 수 없는 경우가 많으므로 이 방법을 제한적으로 사용할 수 있습니다.
오류 로그 이해하기
PHP 오류에는 다음과 같은 에러 유형이 있습니다.
- Fatal Error (치명적인 오류): 사이트 작동을 완전히 중단시키는 심각한 오류
- Warning (경고): 심각하지 않지만 주의가 필요한 오류
Fatal Error는 반드시 해결해야 하지만 Warning은 심각하지 않기 때문에 반드시 해결해야 하는 것은 아닙니다.
Fatal Error의 원인은 다양합니다. 예시:
- 정의되지 않은 함수 호출: Fatal error: Uncaught Error: Call to undefined function…
- 존재하지 않는 클래스 참조: Fatal error: Uncaught Error: Class ‘ClassName’ not found…
- PHP 구문 오류: Fatal error: Parse error: syntax error, unexpected ‘{‘…
- 메모리 부족 오류: Fatal error: Allowed memory size of X bytes exhausted…
- 플러그인/테마 충돌로 인한 오류: Fatal error: Cannot redeclare function/class…
- 파일 접근 권한 오류: Fatal error: Uncaught Error: Failed to open required file…
위와 같은 오류가 발생하면 사이트에 심각한 오류가 발생한 것이므로 반드시 문제의 원인을 찾아서 해결해야 합니다.
PHP 구문 오류는 PHP 버전이 호환되지 않거나 PHP 문법이 잘못되어 흔히 나타납니다. 예를 들어, 다음과 같은 구문 오류가 클라우드웨이즈나 카페24에서 호스팅되는 사이트에 발생할 수 있습니다.
Parse error: Unmatched '}' in /home/123456.cloudwaysapps.com/abcdefgh/public_html/wp-content/themes/avada-child/single-movie.php on line 139위와 같은 오류가 발생하면 먼저는 해당 오류가 발생하는 파일에서 문제의 코드를 확인하도록 합니다.
<? if(get_field('movie_genre')){ ?>위와 같은 라인에서 오류가 발생할 수 있습니다. 이는 ‘short_open_tag’ 기능이 ‘off’로 설정된 경우, <?를 PHP 코드의 시작으로 인식하지 못해 생기는 문제입니다.
클라우드웨이즈는 기본적으로 ‘short_open_tag’ 기능이 비활성화되어 있습니다. 서버 설정에서 Short Open Tag를 활성화하면 문제가 해결됩니다. 또는 <?를 <?php로 바꾸는 것도 가능합니다. (PHP 코드를 작성할 때, <?와 같은 단축 태그 대신 <?php와 같은 전체 태그를 사용하면 예상치 못한 오류를 방지하는 데 도움이 됩니다.)
경고는 일반적으로 무시할 수 있지만, 가능한 경우 해결하는 것이 바람직합니다. 예를 들어, 이 사이트에는 Tocer라는 목차 플러그인이 설치되어 있는데, 방문자들이 사이트를 방문할 때마다 아래와 같은 오류가 발생하고 있습니다.
PHP Deprecated: Using ${var} in strings is deprecated, use {$var} instead in /home/public_html/public_html/wp-content/plugins/tocer/inc/class-composite.php on line 264이 사이트에는 PHP 8.3 버전이 적용되어 있습니다. Tocer 플러그인이 PHP 8.3과 완전히 호환되지 않아서 이런 오류가 발생하고 있습니다. 하지만 플러그인 기능에는 문제가 없습니다.
비록 플러그인 작동에는 문제가 없지만 이런 오류가 대량으로 반복적으로 발생한다면 서버 리소스를 소진할 수 있어 바람직하지 않습니다. 실제로 이런 문제 때문에 트래픽이 빠르게 소지되는 경우도 있습니다.
문제 해결 후
워드프레스에 치명적인 오류가 발생하는 경우 먼저 디버그 모드를 활성화하여 문제의 원인을 파악한 다음, 문제를 해결할 수 있습니다. 문제 해결을 시도하기 전에 사이트 백업을 하여 PC나 클라우드 스토리지에 보관하는 것이 안전합니다.
구체적으로 다음과 같은 원인으로 인해 워드프레스 사이트 문제가 발생할 수 있습니다.
- 플러그인 호환성 문제
- 플러그인 간 충돌
- 오래된 플러그인과 최신 워드프레스 버전 간 비호환성
- 테마 관련 문제
- 테마와 워드프레스 버전 불일치
- 커스터마이징으로 인한 오류
- 서버 및 웹호스팅 관련 문제
- PHP 설정 값 문제
- 잘못된 서버 세팅
- 데이터베이스(DB) 연결 오류
- PHP 버전 문제 (오래된 PHP 버전)
- 파일 및 권한 문제
- .htaccess 파일 손상
- 부적절한 파일/폴더 권한(퍼미션) 설정
- 보안 및 업데이트 관련 문제
- 오랫동안 업데이트하지 않은 워드프레스 버전
- 멀웨어 (악성코드) 감염
- 보안 취약점
- 사용자 실수
- 잘못된 사이트 주소 변경
- 부적절한 플러그인/테마 설치
- 기술적 문제
- PHP 버전 호환성
- 서버 리소스 부족
- 코어 파일 손상
워드프레스를 안전하게 이용하려면 정기적으로 백업하고 워드프레스 코어, 테마, 플러그인을 항상 최신 버전으로 업데이트하여 최신 상태로 유지해야 합니다. 업데이트를 소홀히 할 경우 멀웨어에 감염되거나 해킹을 당하는 등 보안 문제가 발생할 수 있습니다.
문제가 해결되면 wp-config.php 파일에서 디버그 모드를 다시 비활성화하도록 합니다.
define('WP_DEBUG', false);디버그 모드를 비활성화하지 않고 활성화된 상태로 두면 보안상 문제가 발생할 수 있고, 심각하지 않는 오류(warning)가 방문자들에게 표시될 수 있습니다.
문제가 해결되지 않는 경우
일반적으로 디버그 모드를 활성화하면 사이트에서 발생하는 오류 로그를 확인하여 원인을 파악할 수 있습니다. 그러면 문제 해결 방향을 잡을 수 있습니다.
하지만 앞서 언급했듯이 사이트에 치명적인 오류가 발생하고 있지만 디버그 모드를 활성화해도 아무런 에러 메시지가 표시되지 않는 경우가 있습니다. 이런 경우에는 문제의 원인을 짐작할 수 없으므로 문제 해결이 쉽지 않을 수 있습니다.
문제가 해결되지 않는 경우, 가장 간단한 방법은 사이트를 과거 버전으로 롤백하는 것입니다. 백업본이 있다면 백업본을 사용하여 사이트를 복원할 수 있습니다.
카페24나 패스트코멧, 케미클라우드, 클라우드웨이즈 등의 호스팅에서는 자동 복원 기능을 제공하므로 쉽게 과거 버전으로 되돌릴 수 있습니다.
하지만 사이트를 롤백하면 백업본 이후에 변경된 사항이나 추가된 내용은 모두 사라지므로 신중히 결정하시기 바랍니다.
부록: wp-config.php 파일 위치를 찾을 수 없는 경우
일반 웹호스팅을 이용할 경우 FTP에 접속해 쉽게 wp-config.php 파일을 찾을 수 있습니다. 그러나 AWS나 Vultr처럼 서버를 직접 생성하여 워드프레스 사이트를 운영하는 경우, 설치 경로를 찾는 일이 초보자에게는 까다로울 수 있습니다.
워드프레스 관리자 페이지에 접속할 수 있다면 워드프레스 대시보드 » 도구 » 사이트 건강 » 정보 탭의 디렉터리와 크기 섹션에서 워드프레스 디렉터리 위치를 확인할 수 있습니다.
관리자 페이지에 접속할 수 없는 경우 SSH에 접속하여 다음과 같은 명령을 내려서 확인할 수 있습니다.
find . -name wp-config.php이 방법을 이용하려면 SSH에 대한 접속 권한이 있어야 합니다. 일반적인 웹호스팅에서는 보안 문제 때문에 SSH 액세스 권한을 제공하지 않지만 AWS나 Vultr에서 서버를 운영하는 경우에는 SSH 액세스 권한이 있습니다.