Rank Math 메타 디스크립션 REST API 오류, Code Snippets PHP로 우회하는 법

글쓴이 /

WordPress에서 Rank Math를 쓰다 보면 메타 디스크립션이 REST API 권한 문제로 저장되지 않는 상황을 맞닥뜨릴 수 있습니다. 관리자 계정으로 접속해도 REST API 응답이 막히면 Rank Math 메타 디스크립션 필드 자체가 작동하지 않는 경우가 있습니다. 이때 플러그인 추가 없이 코드 몇 줄로 해결하는 방법이 Code Snippets PHP 우회법입니다.

REST API가 Rank Math 메타 디스크립션을 막는 이유

Rank Math 메타 디스크립션 REST API

Rank Math는 메타 디스크립션을 포함한 SEO 메타 데이터를 저장할 때 WordPress REST API를 경유합니다. 구체적으로는 포스트 메타(post meta) 값을 register_meta() 또는 register_rest_field() 방식으로 REST API에 등록해 에디터(Gutenberg)와 통신하는 구조입니다.

문제는 일부 보안 플러그인이나 서버 설정이 REST API 엔드포인트를 차단하거나, 특정 사용자 권한(capability)이 누락됐을 때 발생합니다. 이 경우 Rank Math 메타박스는 화면에 보이지만 저장 버튼을 눌러도 값이 반영되지 않습니다.

오류 패턴을 정리하면 다음과 같습니다.

  • 브라우저 콘솔에 403 Forbidden 또는 rest_forbidden 오류 출력
  • 포스트 저장 후 메타 디스크립션 필드가 공백으로 초기화됨
  • Rank Math SEO 점수는 표시되지만 실제 소스코드에 meta name="description" 태그가 없음

Code Snippets 플러그인으로 REST API 등록을 직접 처리하는 원리

Rank Math가 REST API를 통해 메타를 저장하지 못한다면, 해당 메타 키를 직접 REST API에 등록해 에디터가 정상적으로 읽고 쓸 수 있도록 만들어 주면 됩니다. 이 작업을 functions.php에 직접 넣어도 되지만, 테마를 바꾸면 코드가 사라지는 위험이 있습니다. Code Snippets 플러그인(wordpress.org/plugins/code-snippets)을 사용하면 테마와 무관하게 PHP 코드를 영구 등록할 수 있습니다.

핵심 원리는 다음과 같습니다.

  1. Rank Math가 사용하는 메타 키(rank_math_description)를 register_meta()로 REST API에 명시적으로 등록합니다.
  2. show_in_rest 값을 true로 설정해 Gutenberg 에디터가 해당 필드를 읽고 쓸 수 있도록 허용합니다.
  3. 저장 훅(save_post)을 추가해 REST API 외 경로로도 값이 저장되도록 이중 처리합니다.

Code Snippets 등록 화면

Rank Math 메타 디스크립션 REST API 등록 코드 작성법

Code Snippets 플러그인을 설치한 뒤, 관리자 메뉴에서 Snippets → Add New로 이동합니다. 아래 코드를 PHP 타입으로 등록합니다.

<?php
add_action( 'init', function() {
    register_meta( 'post', 'rank_math_description', [
        'show_in_rest'  => true,
        'single'        => true,
        'type'          => 'string',
        'auth_callback' => function() {
            return current_user_can( 'edit_posts' );
        },
    ] );
} );

add_action( 'save_post', function( $post_id ) {
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;
    if ( ! current_user_can( 'edit_post', $post_id ) ) return;

    if ( isset( $_POST['rank_math_description'] ) ) {
        update_post_meta(
            $post_id,
            'rank_math_description',
            sanitize_text_field( $_POST['rank_math_description'] )
        );
    }
} );

코드 등록 후 Save Changes and Activate를 클릭합니다. 별도의 테마 수정 없이 즉시 적용됩니다.

적용 전후 비교

항목 적용 전 적용 후
메타 디스크립션 저장 입력해도 공백으로 초기화 정상 저장 및 유지
REST API 오류 콘솔에 403 오류 출력 오류 없음
소스코드 meta 태그 description 태그 없음 입력값 그대로 출력
테마 교체 시 유지 여부 functions.php 방식은 코드 소멸 Code Snippets로 영구 유지

meta description 정상 출력 확인

주의사항과 한계

이 방법은 REST API 차단이 원인일 때 효과적입니다. 다만 모든 환경에서 동일하게 작동한다고 보장하기는 어렵습니다. 적용 전에 아래 사항을 먼저 확인하는 것이 좋습니다.

  • 보안 플러그인 설정 확인: Wordfence, iThemes Security 등에서 REST API를 전체 차단한 경우, 해당 플러그인 설정에서 허용 예외를 추가해야 합니다.
  • Rank Math 버전 확인: Rank Math가 업데이트되면 내부 메타 키 이름이 변경될 수 있습니다. 현재 사용 중인 버전의 실제 메타 키를 get_post_meta()로 확인하는 것이 정확합니다.
  • 캐시 플러그인 초기화: 코드 적용 후에도 이전 캐시가 남아 있으면 소스코드에 변경이 반영되지 않을 수 있습니다. WP Rocket, W3 Total Cache 등을 사용 중이라면 캐시를 초기화합니다.
  • 멀티사이트 환경: WordPress 멀티사이트에서는 register_meta()의 동작 범위가 달라질 수 있으므로 별도 테스트가 필요합니다.

자주 묻는 질문

Q. Code Snippets 플러그인 없이 같은 방법을 쓸 수 있나요?
가능합니다. 자식 테마(child theme)의 functions.php에 동일한 코드를 추가하면 됩니다. 다만 자식 테마를 사용하지 않는 환경이라면 테마 업데이트 시 코드가 삭제될 수 있으므로 Code Snippets 방식이 더 안전합니다.
Q. rank_math_description 외에 다른 Rank Math 메타 키도 같은 방법으로 등록할 수 있나요?
가능합니다. rank_math_title(SEO 제목), rank_math_focus_keyword(핵심 키워드) 등도 동일한 register_meta() 구조로 추가 등록할 수 있습니다. 각 키의 정확한 이름은 Rank Math 공식 문서나 데이터베이스 wp_postmeta 테이블에서 확인할 수 있습니다.
Q. 이 코드를 적용했는데도 여전히 저장이 안 됩니다. 어떻게 해야 하나요?
브라우저 콘솔(F12 → Console 탭)에서 실제 오류 메시지를 확인합니다. rest_cookie_invalid_nonce 오류라면 nonce 처리 문제이고, rest_cannot_edit이라면 권한 설정을 재검토해야 합니다. 오류 메시지 없이 저장만 안 된다면 보안 플러그인의 REST API 차단 설정을 먼저 점검하는 것이 순서입니다.

Rank Math 메타 디스크립션이 REST API 문제로 저장되지 않는 상황은 생각보다 자주 보고됩니다. Code Snippets PHP 우회법은 서버나 테마를 직접 건드리지 않고 처리할 수 있는 현실적인 방법 중 하나입니다. 다만 환경마다 원인이 다를 수 있으므로, 콘솔 오류 메시지를 먼저 확인하고 적용하는 것이 시간을 아끼는 순서입니다.

썸네일: Bernd 📷 Dittrich on Unsplash

댓글 달기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다

위로 스크롤