블록 편집기가 로딩되지 않는 워드프레스 문제 해결하기

블록 편집기가 로딩되지 않는 경우 대부분은 자바스크립트 오류입니다. 플러그인이나 테마의 스크립트 하나가 깨지면 React 앱 전체가 멈춰버리고 편집기가 끝까지 렌더링되지 못합니다. 브라우저 개발자 콘솔을 열고(F12, 맥에서는 Cmd+Option+I), 편집 화면을 새로고침한 뒤 빨간 오류 메시지를 읽어보세요. 오류를 던진 파일 이름이 거의 항상 함께 나옵니다. 그 한 줄이 어떤 플러그인을 비활성화해야 하는지 알려주고, 보통 5분도 안 되어 다시 글쓰기로 돌아갈 수 있습니다. 인터넷에서 가장 흔히 제안하는 세 가지는 워드프레스 재설치, PHP 메모리 한도 상향, 클래식 편집기로 전환인데, 세 가지 모두 대개 잘못된 대처입니다.

편집기가 이런 식으로 깨지는 이유

블록 편집기(구텐베르크)는 wp-admin/post.php와 post-new.php 안에서 동작하는 싱글 페이지 React 애플리케이션입니다. 워드프레스는 wp-blocks, wp-element, wp-editor, wp-edit-post 같은 스크립트 패키지 묶음을 큐에 등록하고, 앱은 wp.domReady()를 통해 부트스트랩됩니다. 자바스크립트는 처음으로 잡히지 않은 예외가 발생하는 순간 실행을 멈춥니다. 그래서 편집기가 초기화되는 도중에 큐에 등록된 스크립트 중 하나라도 예외를 던지면, 그 뒤의 모든 것이 함께 죽어버립니다. 공들여 작성하던 글 영역이 새하얀 빈 화면으로 무너지거나 “편집기에서 예상치 못한 오류가 발생했습니다”라는 메시지가 뜹니다.

또한 워드프레스는 기본적으로 관리자 스크립트를 몇 개의 요청으로 합쳐서 로딩합니다. 즉 어느 플러그인의 깨진 JS가 같은 번들에 실린 아무 관련 없는 스크립트까지 끌어내릴 수 있다는 뜻이고, 그래서 동작만 봐서는 범인이 항상 명확한 것이 아닙니다. 하지만 콘솔은 알려줍니다.

두 번째 유형의 실패는 양상이 다릅니다. 편집기는 로딩되지만 저장할 때 “업데이트에 실패했습니다. 응답이 유효한 JSON 응답이 아닙니다”라는 오류가 뜹니다. 이건 자바스크립트 문제가 아닙니다. 편집기는 /wp-json/wp/v2/에 있는 REST API와 통신하며 깨끗한 JSON이 돌아오길 기대합니다. 만약 플러그인이나 테마의 functions.php가 JSON 앞에 PHP 알림(notice)이나 경고(warning), 치명적 오류를 출력하거나, 보안 플러그인이 REST 경로를 차단하거나, 리다이렉트 플러그인이 URL을 다시 쓰면 응답이 오염되어 편집기가 이를 파싱하지 못합니다.

해결 방법, 가장 빠른 것부터

1. 콘솔을 읽으세요. 개발자 도구를 열어둔 채로 문제를 재현하세요. Uncaught TypeError ... some-plugin/build/index.js 같은 오류는 문제를 일으킨 플러그인을 곧장 가리킵니다. 이 한 단계로 대부분의 경우가 해결되며, 감으로 하나씩 이분 탐색하는 수고를 덜어줍니다.

2. 브라우저 문제를 배제하세요. 강력 새로고침(Cmd/Ctrl+Shift+R)을 한 뒤, 확장 프로그램을 끈 시크릿 창에서 시도해 보세요. 광고 차단기와 개인정보 보호 확장 프로그램이 가끔 관리자 스크립트를 걷어내기도 합니다. 시크릿 창에서 잘 된다면 문제는 브라우저 확장 프로그램이나 오래된 캐시이지 사이트가 아닙니다.

3. REST API를 직접 확인하세요. “유효한 JSON이 아닙니다” 메시지를 봤다면, 브라우저에서 https://yoursite.com/wp-json/에 접속해 보세요. JSON이 가득 나와야 정상입니다. HTML이나 500 오류, 또는 로그인 리다이렉트가 나온다면 그게 바로 문제입니다. 편집기 자체가 아니라 어떤 플러그인이 REST 응답을 망가뜨리고 있는 것입니다.

4. 플러그인을 이분 탐색하세요. 전부 비활성화하고 편집기가 로딩되는지 확인한 다음, 다시 깨질 때까지 하나씩 활성화하세요. wp-admin에 아예 접근할 수 없다면 SFTP로 폴더 이름을 바꿔서 처리하세요.

mv wp-content/plugins wp-content/plugins_off

폴더가 사라지면 워드프레스는 모든 플러그인을 비활성화합니다. 이름을 원래대로 되돌린 뒤, 플러그인을 하나씩 넣었다 뺐다 하며 확인하세요.

5. 테마를 테스트하세요. Twenty Twenty-Four로 전환하세요. 깨진 편집기 JS를 큐에 등록하거나 functions.php에서 PHP 오류를 던지는 테마도 같은 증상을 일으킵니다.

6. 로그를 켜고 진짜 오류를 읽으세요. 특히 REST/JSON 실패의 경우, wp-config.php에서 디버깅을 활성화하세요.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

치명적 오류는 정확한 파일명과 줄 번호와 함께 wp-content/debug.log에 기록됩니다. 그 스택 트레이스가 복잡하다면 — 네임스페이스가 붙은 클래스명, require 체인, 열 줄짜리 트레이스 아래에 묻힌 치명적 오류 등 — 워드프레스 오류 로그 디코더에 붙여넣어 어떤 플러그인의 몇 번째 줄이 실제로 이를 일으켰는지 쉬운 말로 확인하세요. 그것이 “뭔가 고장났다”와 “이 특정 플러그인의 214번째 줄이 고장났다”의 차이입니다.

스크립트 합치기(concatenation)가 진짜 범인을 가리고 있다고 의심된다면, 각 스크립트를 개별적으로 로딩하도록 강제해서 콘솔 오류가 정확히 파일 하나를 가리키게 하세요.

define( 'SCRIPT_DEBUG', true );
define( 'CONCATENATE_SCRIPTS', false );

하지 말아야 할 것

클래식 편집기 플러그인을 설치하고 해결됐다고 여기지 마세요. 그건 아무것도 고치지 못합니다. 단지 블록 편집기를 숨겨서 오류가 안 보이게 할 뿐입니다. 깨진 자바스크립트나 깨진 REST 응답은 그대로 남아 있고, 사이트 편집기나 위젯에서, 혹은 다음 업데이트 때 다시 발목을 잡을 것입니다. 먼저 진단하세요. 블록 사용을 그만두겠다고 의도적으로 결정한 경우에만 클래식으로 물러나세요.

반사적으로 PHP 메모리 한도를 올리지 마세요. 인터넷이 가장 좋아하는 복붙 해결책이지만, 빈 편집기가 메모리 부족 때문인 경우는 드뭅니다. 진짜 메모리 부족은 특정한 치명적 오류를 던집니다 — “Allowed memory size of N bytes exhausted” — 이 메시지는 debug.log에서 보게 됩니다. 그 줄이 없다면 메모리를 늘려도 아무것도 달라지지 않습니다.

워드프레스 코어를 재설치하지 마세요. 코어 파일은 모든 설치본에서 바이트 단위로 동일합니다. 코어가 문제라면 지금 지구상의 모든 워드프레스 사이트에서 편집기가 깨져 있을 것입니다. 원인은 거의 항상 플러그인이나 테마에 있으며, 코어 재설치는 아무것도 고치지 못하면서 오히려 다른 것을 덮어쓸 위험만 있습니다.

첫 단계부터 무작정 캐시 플러그인을 비우거나 끄지 마세요. 공격적인 JS 압축(minification)과 합치기가 편집기를 깨뜨릴 수 있으니 테스트해 볼 가치는 있습니다. 하지만 아무데나 캐시를 비우기 전에 먼저 콘솔을 확인하세요. 추측으로 접근하는 것이 5분짜리 해결을 반나절짜리로 만드는 길입니다.

그래도 막혔다면

콘솔이 깨끗하고, REST API가 유효한 JSON을 반환하며, 플러그인과 테마를 전부 이분 탐색해도 편집기가 여전히 죽어 있다면, 답은 거의 항상 debug.log 안에 있습니다. WP_DEBUG_LOG를 활성화하고, 문제를 한 번 재현한 뒤, 나오는 치명적 오류를 오류 로그 디코더에 돌려보세요. 스택 트레이스가 파일 이름을 알려줍니다. 거기서부터 시작하세요.