naver.HOW data lake by AI

Nginx와 WordPress 연동 시 URL 매핑 문제 해결하기

Written by

sp

in

웹 서버를 구성할 때 가장 흔히 마주치는 문제 중 하나는 서로 다른 애플리케이션 간의 URL 매핑입니다. 특히 Nginx와 WordPress를 함께 사용할 때 종종 이러한 문제가 발생합니다. 이번 글에서는 Nginx 서버에서 WordPress 사이트를 호스팅할 때 자주 발생하는 URL 매핑 문제와 그 해결책을 상세히 살펴보겠습니다.

문제 상황: WordPress 링크 깨짐 현상

WordPress 사이트를 서브 디렉토리에 설치하고 Nginx로 서빙할 때, 흔히 발생하는 문제는 메인 페이지는 정상적으로 로드되지만 개별 글 페이지로 이동하면 ‘404 Not Found’ 오류가 발생하는 것입니다. 이는 대개 다음과 같은 상황에서 발생합니다:

  1. WordPress가 /wp와 같은 서브 디렉토리에 설치됨
  2. 메인 사이트 URL과 WordPress URL 간의 매핑이 제대로 설정되지 않음
  3. Nginx의 location 블록과 try_files 지시어가 올바르게 구성되지 않음

원인 분석

이 문제의 핵심은 Nginx 설정과 WordPress의 내부 URL 처리 방식의 불일치에 있습니다. WordPress는 .htaccess 파일을 통한 URL 재작성을 기본적으로 사용하지만, Nginx는 이 파일을 인식하지 않습니다. 따라서 Nginx에서는 WordPress의 퍼머링크 구조를 명시적으로 지원하는 설정이 필요합니다.

또한, Nginx의 alias 지시어와 try_files 지시어가 함께 사용될 때 발생하는 특수한 동작 방식도 문제의 원인이 될 수 있습니다. alias는 URI 경로를 다른 파일 시스템 경로로 매핑하는데, 이 과정에서 try_files와의 상호작용이 예상대로 작동하지 않을 수 있습니다.

해결 방법

1. 올바른 Nginx 설정 구성

Nginx 설정에서 WordPress용 location 블록을 다음과 같이 구성해보세요:

# WordPress 디렉토리에 대한 처리
location ^~ /wp {
    alias /var/www/example.com/wp;
    index index.php;
    
    # WordPress 퍼머링크를 위한 설정
    try_files $uri $uri/ @wordpress;
    
    # PHP 파일 처리
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $request_filename;
        fastcgi_pass unix:/var/run/php/php-fpm.sock;
    }
}

# WordPress 퍼머링크 처리를 위한 명명된 location
location @wordpress {
    rewrite /wp/(.*)$ /wp/index.php?$args last;
}

이 설정의 핵심은 @wordpress라는 명명된 위치(named location)를 사용하여 WordPress의 모든 요청을 index.php로 재작성하는 것입니다. 이는 WordPress의 퍼머링크 시스템이 작동하는 방식과 일치합니다.

2. WordPress URL 설정 확인

WordPress 관리자 패널의 ‘설정 > 일반’ 메뉴에서 다음 항목이 올바르게 설정되어 있는지 확인하세요:

  • WordPress 주소(URL): https://example.com/wp
  • 사이트 주소(URL): https://example.com

이 설정은 WordPress가 자체 URL을 구성하는 방식을 결정합니다. 잘못 설정되면 링크가 깨질 수 있습니다.

3. 퍼머링크 설정 재구성

WordPress 관리자 패널에서 ‘설정 > 퍼머링크’로 이동하여 퍼머링크 구조를 확인하고 변경해보세요. 가장 일반적으로 사용되는 ‘게시물 이름'(/%postname%/) 구조가 권장됩니다. 설정을 변경하고 저장하면 WordPress가 내부 재작성 규칙을 재구성합니다.

더 간단한 대안 설정

복잡한 디렉토리 구조가 필요하지 않다면, WordPress를 루트 디렉토리에 직접 설치하는 것이 URL 매핑 문제를 피하는 가장 간단한 방법입니다. 이 경우 Nginx 설정은 다음과 같이 단순화할 수 있습니다:

server {
    server_name example.com www.example.com;
    
    root /var/www/example.com/wp;
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ /index.php?$args;
    }
    
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php-fpm.sock;
    }
    
    # SSL 설정은 필요에 따라 추가
}

이 설정은 WordPress가 사이트의 루트 디렉토리에 설치되었을 때 가장 잘 작동합니다.

고급 URL 매핑 전략

더 복잡한 URL 구조가 필요한 경우, Nginx의 map 지시어와 조건부 재작성 규칙을 활용할 수 있습니다:

map $uri $is_wp_uri {
    ~^/(wp-admin|wp-content|wp-includes|category|tag|author)/ 1;
    ~^/20[0-9]{2}/(0[1-9]|1[0-2])/(0[1-9]|[1-2][0-9]|3[0-1])/ 1;
    default 0;
}

server {
    # ... 기본 서버 설정 ...
    
    # URL 기반 조건부 처리
    if ($is_wp_uri = 1) {
        rewrite ^/(.*)$ /wp/$1 last;
    }
    
    # ... 나머지 설정 ...
}

이 방식은 특정 패턴의 URL을 자동으로 WordPress 디렉토리로 매핑합니다. 단, Nginx에서 if 지시어의 사용은 주의해야 하며, 가능한 location 블록을 사용하는 것이 권장됩니다.

주의사항 및 디버깅 팁

Nginx 설정을 변경할 때마다 다음 명령으로 구성 파일의 문법을 검사하세요:

sudo nginx -t

오류가 없다면 Nginx를 재시작하여 변경사항을 적용합니다:

sudo systemctl restart nginx

또한, Nginx와 PHP-FPM의 오류 로그를 확인하면 문제 해결에 도움이 됩니다:

sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/php-fpm/www-error.log

결론

Nginx와 WordPress의 연동 과정에서 발생하는 URL 매핑 문제는 주로 설정 파일의 구성과 관련이 있습니다. 올바른 location 블록 설정, 명명된 위치의 활용, 그리고 WordPress 내부 설정의 조정을 통해 대부분의 문제를 해결할 수 있습니다.

복잡한 URL 구조가 필요한 경우 Nginx의 고급 기능을 활용할 수 있지만, 가능하다면 단순한 디렉토리 구조를 사용하는 것이 유지보수와 문제 해결 측면에서 유리합니다. 웹 서버 설정은 사이트의 안정성과 성능에 직접적인 영향을 미치므로, 변경 사항을 신중하게 테스트하고 적용하는 것이 중요합니다.

코멘트

답글 남기기

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

More posts