워드프레스 GeneratePress 테마: 'generatepress-content-width' 오류 해결 방법

1년 전부터 GeneratePress 테마가 설치된 일부 워드프레스 사이트에서 위젯 페이지를 방문하면 "generatepress-content-width" 플러그인이 오류가 발생했으며 실행할 수 없습니다 경고가 표시되는 문제가 발생하고 있습니다.

GeneratePress 테마가 업데이트되면 이 문제가 해결되지 않을까 기대했지만 아직까지 이 문제가 발생합니다. 최근 워드프레스 7.0이 공개되었는데, 워드프레스 7.0에서는 혹시 이 에러가 발생하지 않을까 하여 확인해 보니 여전히 경고가 표시되네요.

이 문제가 발생하면 간단한 코드를 차일드 테마의 함수 파일에 추가하여 문제를 해결할 수 있습니다. 차일드 테마를 설치하는 것에 부담을 느끼거나 FTP에 접속하여 파일을 수정할 수 없는 사용자들을 위해 해당 코드로 간단한 플러그인을 만들어 보았습니다.😄

워드프레스 GeneratePress 테마: 'generatepress-content-width' 오류 해결 방법

오류의 원인

generatepress-content-width는 GeneratePress 테마가 블록 에디터(Gutenberg) 에 등록하는 플러그인(슬롯)입니다. 이 플러그인은 포스트/페이지 편집 화면을 기준으로 설계되어 있는데, 위젯 편집 화면(widgets.php)도 블록 에디터 기반이다 보니 동일한 JS가 로드됩니다.

문제는 위젯 화면에는 GP가 기대하는 특정 블록 에디터 컨텍스트(예: 포스트 메타, 사이드바 패널 등)가 없어서, 플러그인 초기화 중 의존 객체나 슬롯을 찾지 못하고 런타임 오류가 발생하는 것입니다. GeneratePress 측의 미처리된 호환성 문제입니다.

해결 방법

간단하게는 다음과 같은 코드를 차일드 테마의 함수 파일에 추가하면 오류가 사라집니다.

add_filter('use_widgets_block_editor', '__return_false');

상기 코드는 워드프레스 5.8부터 기본으로 적용된 블록 기반 위젯 편집 화면을 비활성화하고, 그 이전 버전의 클래식 위젯 UI로 되돌리는 코드입니다. 이 필터가 적용되면 관리자의 위젯 편집 화면에서 블록 에디터가 로드되지 않고 기존의 드래그 앤 드롭 방식의 레거시 위젯 화면이 표시되며, 위젯 영역에 블록을 삽입하는 기능 전체가 비활성화됩니다.

하지만 이 코드는 generatepress-content-width 오류의 근본 원인을 해결하는 것이 아니라, 오류가 발생하는 화면 자체를 없애버리는 우회 방식이기 때문에 권장하지 않습니다. 워드프레스는 5.8 이후 블록 위젯을 공식 방향으로 채택하였고 클래식 위젯 UI는 언제든 공식 지원이 종료될 수 있어 장기적으로 안정성을 보장하기 어렵습니다. 또한 이 코드를 적용하면 현재뿐만 아니라 향후 위젯 영역에서 블록을 활용할 가능성까지 원천 차단되므로, 특정 플러그인의 JS 충돌 문제를 해결하기 위한 수단으로는 영향 범위가 지나치게 넓습니다.

저는 다음과 같은 코드를 차일드 테마의 함수 파일에 추가했습니다.

// 위젯 화면에서 GP Content Width 플러그인 오류 방지
add_action( 'admin_enqueue_scripts', function( $hook_suffix ) {
	if ( 'widgets.php' !== $hook_suffix ) {
		return;
	}

	if ( ! wp_script_is( 'wp-plugins', 'registered' ) ) {
		return;
	}

	wp_add_inline_script(
		'wp-plugins',
		'wp.domReady( function() {
			if ( wp.plugins && wp.plugins.unregisterPlugin ) {
				wp.plugins.unregisterPlugin( "generatepress-content-width" );
			}
		} );'
	);
} );

이 코드는 워드프레스 관리자의 위젯 편집 화면(widgets.php)에서 GeneratePress 테마가 블록 에디터에 등록한 generatepress-content-width JS 플러그인을 선택적으로 해제하여 오류를 방지하는 함수입니다. admin_enqueue_scripts 훅을 통해 위젯 화면에서만 동작하도록 제한하고, wp-plugins 스크립트가 등록된 경우에만 실행되도록 조건을 검사한 뒤, wp.domReady() 콜백 안에서 wp.plugins.unregisterPlugin()의 존재 여부까지 확인한 후 해당 플러그인을 등록 해제합니다. 이로써 블록 위젯 화면 자체는 유지하면서 오류를 유발하는 JS만 핀포인트로 제거하기 때문에, 위젯 블록 편집 기능에는 영향을 주지 않으면서도 콘솔 오류와 화면상의 오류 메시지를 깔끔하게 해결할 수 있습니다.

차일드 테마를 만들고 싶지 않거나 파일 수정을 위해 FTP에 접속하는 것에 부담을 느끼는 경우 다음 네이버 카페 게시글에서 플러그인을 다운로드하여 설치할 수 있습니다. (동일한 코드를 플러그인으로 만든 것입니다.)

워드프레스 "generatepress-content-width" 플러그인이 오류가 발생했으며 실행할 수 없습니다 오류 해결

다운로드한 zip 파일을 업로드하여 설치할 수 있습니다.

1. 워드프레스 관리자 페이지에 접속합니다.
2. 플러그인 » 플러그인 추가로 이동합니다.
3. 상단의 '플러그인 업로드' 버튼을 클릭합니다.
4. ZIP 파일을 끌어서 놓거나 파일을 지정하여 설치합니다.
5. 플러그인을 활성화합니다.

매우 간단한 코드이기 때문에 사이트 속도에 거의 영향을 미치지 않습니다. FTP에 접속할 수 있다면 상기 코드를 차일드 테마의 함수 파일에 붙여넣는 것을 권장합니다.

참고

https://blog.avada.co.kr/3906

GeneratePress 테마 Marketer 사이트 템플릿 커스텀 방법

https://blog.avada.co.kr/3046

해외웹호스팅: 클라우드웨이즈 vs. 블루호스트 vs. 카페24 비교 (Cloudways vs. Bluehost vs. Cafe24)