카페24 그누보드 흰 화면 오류, 원인 찾는 법 — 백지 화면 뒤에 숨은 PHP 오류 확인하기
사이트에 접속했는데 아무것도 없는 하얀 화면만 보인 적 있으신가요?
에러 메시지조차 없어서 무엇이 잘못됐는지 알 수 없을 때,
그 원인을 찾는 방법을 정리했습니다.
어느 날 갑자기, 사이트가 하얀 화면이 되었습니다
그누보드나 영카트로 사이트를 운영하다 보면 한 번쯤 겪게 되는 순간이 있습니다.
어제까지 멀쩡하던 페이지가 오늘은 아무것도 없는 하얀 화면만 띄웁니다.
에러 메시지라도 떠 있으면 그걸 단서로 검색이라도 해볼 텐데, 화면은 그냥 새하얗습니다.
어디서부터 손대야 할지 막막합니다.
특히 카페24(Cafe24) 호스팅을 쓰신다면 이 상황을 더 자주 만나게 될텐데요.
이 글에서는 왜 흰 화면이 뜨는지,
그리고 그 뒤에 숨은 진짜 원인을 어떻게 찾아내는지를 직접 겪은 경험을 바탕으로 정리했습니다.
왜 오류 메시지도 없이 흰 화면만 뜰까?
결론부터 말하면, 오류가 없는 게 아니라 오류를 화면에 보여주지 않도록 설정되어 있기 때문입니다.
PHP에는 display_errors라는 설정이 있습니다.
이 설정이 켜져 있으면 오류가 발생했을 때 그 내용이 화면에 표시되고, 꺼져 있으면 오류가 나도 화면에는 아무것도 나오지 않습니다.
그 결과가 바로 흰 화면입니다.
카페24를 비롯한 대부분의 공유 호스팅은 보안상의 이유로 display_errors를 꺼둡니다.
오류 메시지에는 파일 경로나 내부 구조 같은 민감한 정보가 담기는데, 그게 방문자에게 그대로 노출되면 보안에 취약해지기 때문입니다.
즉, 흰 화면은 호스팅이 일부러 만든 상태입니다. 문제는 — 운영자인 우리까지 오류를 못 보게 된다는 점입니다.
그래서 원인을 찾으려면, 진단하는 동안만 잠시 오류가 보이도록 직접 설정을 바꿔줘야 합니다.
카페24에는 에러 로그 메뉴가 없습니다
다른 호스팅 중에는 관리 화면에서 에러 로그를 바로 볼 수 있는 곳도 있습니다.
하지만 카페24 호스팅 관리 화면에는 에러 로그를 확인하는 메뉴가 따로 없습니다.
그래서 카페24에서 흰 화면의 원인을 찾으려면 방법은 두 가지뿐입니다.
.htaccess파일을 수정해서 오류가 화면에 보이도록 만든다- 오류 로그가 파일로 기록되도록 설정한다
이 글에서는 가장 빠르게 원인을 확인할 수 있는 첫 번째 방법을 중심으로 설명합니다.
시작하기 전에 — 반드시 백업하세요
.htaccess는 사이트 전체의 동작을 좌우하는 민감한 파일입니다.
한 글자만 잘못 입력해도 사이트 전체가 500 에러로 멈출 수 있습니다.
그러니 수정하기 전에 반드시 원본을 백업하세요.
- FTP로 접속해 사이트 최상위 폴더에서
.htaccess파일을 찾습니다 - 이 파일을 컴퓨터로 내려받아 두거나, 같은 위치에
.htaccess_backup같은 이름으로 복사해 둡니다
문제가 생기면 백업본을 원래 이름으로 되돌리면 됩니다.
이 단계가 만일의 사고를 막아줍니다.
참고:
.htaccess는 점(.)으로 시작하는 파일이라 FTP 프로그램에서 기본적으로 숨겨져 있을 수 있습니다.
파일이 보이지 않는다면 FTP 프로그램의 옵션에서 “숨김 파일 표시”를 켜주세요.
.htaccess로 흰 화면 뒤의 오류 드러내기
백업을 마쳤다면, .htaccess 파일을 열어 아래 두 줄을 추가합니다.
php_value error_reporting 6135
php_flag display_errors on각 줄의 의미는 이렇습니다.
display_errors on— 오류를 화면에 표시하도록 켭니다. 이게 핵심입니다.error_reporting 6135— 표시할 오류의 범위를 지정합니다. 이 값은 치명적인 오류와 경고 등 원인 파악에 필요한 수준의 오류를 보여줍니다.
저장한 뒤 흰 화면이 뜨던 페이지를 다시 새로고침해 보세요.
이제 백지 대신 빨간 글씨의 오류 메시지가 나타날 것입니다.
오류 메시지에는 보통 이런 정보가 담겨 있습니다.
- 오류의 종류 (Warning, Fatal error, Parse error 등)
- 오류가 발생한 파일의 경로
- 오류가 발생한 줄 번호
바로 이 정보가 문제 해결의 출발점입니다.
이 방법이 통하지 않는다면
.htaccess에 위 설정을 넣었는데도 여전히 흰 화면이라면, 서버의 PHP 구동 방식에 따라 php_value, php_flag 명령이 적용되지 않는 경우입니다.
이럴 때는 흰 화면이 뜨는 PHP 파일의 가장 윗부분(<?php 바로 아래)에 아래 코드를 직접 넣어 보세요.
ini_set('display_errors', 1);
error_reporting(E_ALL);이 방법은 해당 파일에 한해 오류를 화면에 표시해 줍니다.
원인을 확인한 뒤에는 이 코드도 반드시 다시 지워야 합니다.
가장 중요한 단계 — 진단이 끝나면 원래대로 되돌리세요
오류의 원인을 확인했다면, 추가했던 설정을 반드시 제거하세요.
display_errors를 켜둔 상태로 두면, 앞으로 사이트에서 오류가 날 때마다 그 내용이 방문자에게도 그대로 보입니다.
오류 메시지에 담긴 파일 경로 등은 보안에 좋지 않고, 사이트도 지저분해 보입니다.
.htaccess에 추가한 두 줄을 삭제합니다- 또는 PHP 파일에 넣은
ini_set코드를 삭제합니다
display_errors를 켜는 것은 어디까지나 원인을 찾는 동안만 쓰는 임시 조치입니다.
진단이 끝나면 원래의 안전한 상태로 되돌리는 것까지가 한 세트입니다.
오류를 찾은 다음 — 어떻게 고칠까
화면에 뜬 오류 메시지에는 문제가 발생한 파일 경로와 줄 번호가 적혀 있습니다.
해당 파일을 FTP로 내려받아 그 줄을 열어보면, 대부분의 경우 어디가 문제인지 단서를 잡을 수 있습니다.
실제로 흰 화면을 해결할 때는, 오류 메시지가 가리키는 파일과 줄을 찾아 그 부분의 코드를 하나씩 점검하고 수정하면서 문제를 좁혀가게 됩니다.
오류 메시지의 내용(예: Trying to access array offset on value of type null 같은 문구)을 그대로 검색하면, 같은 문제를 겪은 사례와 해결 방법을 찾을 수 있는 경우도 많습니다.
핵심은 — 흰 화면 상태에서는 아무것도 할 수 없지만, 오류 메시지만 보이면 해결의 실마리가 생긴다는 것입니다.
그래서 가장 먼저 할 일이 바로 “오류를 보이게 만드는 것”입니다.
매번 흰 화면이 뜬 뒤에야 알아차리는 게 맞을까?
지금까지의 방법은 이미 흰 화면이 뜬 뒤에 원인을 찾는 과정입니다.
그런데 한 가지 생각해 볼 점이 있습니다.
.htaccess를 켜서 오류를 확인하려면, 일단 누군가 그 흰 화면을 마주쳐야 합니다.
대개는 방문하던 고객이 먼저 보게 되고, 운영자는 그 뒤에야 알게 됩니다.
이미 피해가 생긴 다음입니다.
그래서 평소에는 display_errors를 꺼두어 방문자에게 오류를 숨기되, 오류가 발생하는 순간 운영자에게만 따로 알림이 오도록 해두면 이 문제를 미리 잡을 수 있습니다.
이런 용도로 만든 무료 도구가 있습니다.
그누보드 운영지킴이는 그누보드5·영카트5에서 발생하는 PHP 오류를 자동으로 감지해 기록하고, 메일이나 SMS로 알려주는 무료 오픈소스 플러그인입니다.
흰 화면 뒤에 숨은 오류도 로그로 남겨주기 때문에, .htaccess를 매번 켜고 끄지 않아도 무슨 오류가 어디서 났는지 확인할 수 있습니다.
물론 이 글에서 설명한 .htaccess 방법만으로도 흰 화면의 원인은 충분히 찾을 수 있습니다.
다만 “오류가 난 뒤에 찾는 것”과 “오류가 나는 순간 아는 것”의 차이는 꽤 큽니다.
정리
- 카페24에서 흰 화면이 뜨는 이유는
display_errors가 꺼져 있어 오류가 화면에 표시되지 않기 때문입니다. - 카페24에는 에러 로그 메뉴가 없으므로,
.htaccess수정 또는 PHP 코드 추가로 오류를 직접 드러내야 합니다. .htaccess를 수정하기 전에는 반드시 백업하세요.- 오류를 확인한 뒤에는 추가한 설정을 반드시 제거해, 방문자에게 오류가 노출되지 않게 하세요.
- 오류 메시지의 파일 경로와 줄 번호가 문제 해결의 출발점입니다.
흰 화면은 막막하지만, 그 뒤에 숨은 오류만 보이게 만들면 해결의 실마리는 반드시 잡힙니다.
이 글이 같은 상황을 겪는 분께 도움이 되길 바랍니다.