SPA 웹사이트 구글 검색 노출 누락 - Dynamic Rendering과 프리렌더링 구축으로 CSR 검색 색인 완벽 해결

React나 Vue 같은 프레임워크로 멋지게 개발한 SPA 웹사이트를 오픈했는데 구글 검색 결과에 빈 페이지가 뜨거나 색인이 아예 생기지 않는 현상을 경험해봤을 것이다.
다만 대부분의 개발자들은 '구글 크롤러는 자바스크립트를 잘 실행해주니까 문제없겠지'라고 막연하게 생각하다가 검색 노출이 통째로 날아간 뒤에야 원인을 찾기 시작한다.
이번에는 클라이언트 사이드 렌더링(CSR) 환경에서 검색엔진 크롤러가 페이지를 정상 수집하도록 만드는 동적 렌더링(Dynamic Rendering)의 정확한 원리와 Node.js 기반 프리렌더링 서버를 구축해 완벽히 해결하는 방법을 소개하겠다.

CSR(Client Side Rendering) 방식의 앱은 서버에서 비어 있는 HTML 껍데기와 자바스크립트 번들 파일만 응답한다. 브라우저가 이 자바스크립트를 실행한 뒤에야 비로소 화면에 실제 데이터와 DOM 요소가 그려지는 구조다.
구글 봇과 같은 최신 검색엔진 크롤러가 자바스크립트 실행 엔진을 탑재하고 있는 것은 사실이다. 하지만 렌더링 과정에서 막대한 컴퓨팅 자원이 소모되기 때문에 크롤러는 일단 HTML만 빠르게 수집(HTML 파싱 단계)하고 자바스크립트 실행 작업(렌더링 단계)은 렌더링 큐에 쌓아둔 뒤 나중에 여유가 있을 때 처리한다.

문제는 이 렌더링 타임아웃 시간이 꽤 짧고, 네이버(Yeti)나 다음, 기타 검색엔진의 크롤러는 자바스크립트를 완전히 실행하지 못하는 경우가 허다하다는 점이다.
결과적으로 크롤러는 <div id="root"></div> 처럼 텅 비어있는 HTML만 읽어가게 되고, 검색엔진은 페이지에 아무런 내용이 없다고 판단해 색인 생성에서 제외하거나 평가를 하락시킨다.

사이트 전체를 SSR(Server Side Rendering) 프레임워크인 Next.js나 Nuxt.js로 마이그레이션하는 것은 기존 대규모 프로젝트에서 엄청난 시간과 비용이 들어간다.
이때 가장 현실적이고 강력한 대안이 바로 동적 렌더링이다.

동적 렌더링은 웹 서버(Nginx 등) 앞단에서 요청을 보낸 주체의 User-Agent 헤더를 감지하는 방식으로 동작한다.
일반 사용자가 접속하면 기존처럼 CSR용 HTML과 자바스크립트 파일 그대로 응답하여 빠른 SPA UX를 제공한다.
반면 구글 봇, 네이버 Yeti, 페이스북 scrapbot 등 크롤러가 접속하면 요청을 미들웨어나 프리렌더(Pre-render) 서버로 우회시킨다.
프리렌더 서버는 헤드리스 브라우저(Puppeteer 등)를 실행해 자바스크립트까지 완벽히 실행된 상태의 HTML 결과물만 캡처하여 크롤러에게 전달한다.

실무에서 자주 하는 실수는 Nginx 미들웨어 없이 크롤러 판단을 클라이언트 사이드 자바스크립트 내부에서 처리하려는 시도다. 이는 크롤러가 자바스크립트 자체를 안 돌리면 무용지물이 된다.

✗ 아래처럼 프론트엔드 코드 내에서 Navigator 사용자 정보로 조건문을 걸어도, 크롤러가 자바스크립트 해석을 건너뛰면 렌더링된 결과를 수집할 수 없다.

// Client-side script (작동하지 않음)
if (navigator.userAgent.includes('Googlebot')) {
  // 이미 자바스크립트 파싱 단계에 들어가지 못하면 이 코드 자체가 실행되지 않는다.
  fetchDataAndRenderDirectly();
}

✓ 올바른 방식은 웹 서버(Nginx) 레벨에서 HTTP 요청 헤더의 User-Agent를 확인하여 크롤러 요청만 Puppeteer 프리렌더링 서비스로 라우팅하는 것이다.

server {
    listen 80;
    server_name example.com;

    location / {
        # 크롤러 여부를 판단하기 위한 변수
        set $prerender 0;
        
        # 대표적인 검색엔진 크롤러 및 소셜 봇 User-Agent 감지
        if ($http_user_agent ~* "googlebot|bingbot|yeti|naversearchbot|baiduspider|twitterbot|facebookexternalhit|rogerbot|linkedinbot|embedly|quora link preview|showyoubot|outbrain|pinterest") {
            set $prerender 1;
        }

        # 정적 리소스(JS, CSS, 이미지 등) 요청은 프리렌더 대상에서 제외
        if ($uri ~* "\.(js|css|xml|less|png|jpg|jpeg|gif|pdf|doc|txt|ico|rss|zip|mp3|rar|exe|wmv|doc|avi|ppt|mpg|mpeg|tif|wav|mov|psd|ai|xls|mp4|m4a|swf|dat|dmg|iso|flv|m4v|torrent|ttf|woff|svg|eot)") {
            set $prerender 0;
        }

        # 크롤러인 경우 3000번 포트의 Express Puppeteer 서버로 프록시
        if ($prerender = 1) {
            rewrite ^/(.*)$ /render?url=https://example.com/$1 break;
            proxy_pass http://127.0.0.1:3000;
        }

        # 일반 사용자는 기존 static 파일 제공
        root /var/www/html/dist;
        try_files $uri $uri/ /index.html;
    }
}

const express = require('express');
const puppeteer = require('puppeteer');

const app = express();
let browser;

// 서버 시작 시 Puppeteer 브라우저 인스턴스 미리 생성
(async () => {
  browser = await puppeteer.launch({
    args: ['--no-sandbox', '--disable-setuid-sandbox']
  });
})();

app.get('/render', async (req, res) => {
  const targetUrl = req.query.url;

  if (!targetUrl) {
    return res.status(400).send('URL parameter is required');
  }

  try {
    const page = await browser.newPage();
    
    // 크롤러용이므로 폰트나 이미지 로딩을 차단하여 속도 최적화
    await page.setRequestInterception(true);
    page.on('request', (req) => {
      const resourceType = req.resourceType();
      if (['image', 'stylesheet', 'font'].includes(resourceType)) {
        req.abort();
      } else {
        req.continue();
      }
    });

    // 페이지 이동 및 자바스크립트 실행 완결(networkidle0) 대기
    await page.goto(targetUrl, { waitUntil: 'networkidle0', timeout: 15000 });

    // 동적 렌더링이 완료된 HTML 추출
    const html = await page.content();
    await page.close();

    // 완벽한 static HTML 응답
    res.status(200).send(html);
  } catch (error) {
    console.error(`Rendering error for ${targetUrl}:`, error);
    res.status(500).send('Failed to render page');
  }
});

app.listen(3000, () => {
  console.log('Pre-renderer server running on port 3000');
});

설정 후 크롤러 타겟으로 조회했을 때의 결과는 다음과 같다.

# 일반 사용자 curl 요청 (기존 CSR HTML 응답)
$ curl -A "Mozilla/5.0" https://example.com
<html><head></head><body><div id="root"></div><script src="/app.js"></script></body></html>

# 구글 봇 curl 요청 (프리렌더링된 완성형 HTML 응답)
$ curl -A "Googlebot" https://example.com
<html><head><title>실무 개발 블로그</title></head><body><div id="root"><h1>동적 렌더링 완료된 텍스트</h1><p>검색엔진이 수집할 수 있는 정적 데이터</p></div></body></html>

동적 렌더링을 올바르게 구축하지 않으면 구글 검색 알고리즘에 의해 제재를 받거나 서버가 멈추는 불상사가 발생할 수 있다.

1. 클로킹(Cloaking) 제재 위험 방지
검색엔진은 사용자가 보는 콘텐츠와 크롤러에게 제공하는 콘텐츠가 크게 다를 경우 패널티를 부여한다(클로킹 행위). 프리렌더 서버가 크롤러에게 전달하는 HTML 텍스트 내용이 실제 브라우저에서 사용자가 보는 최종 DOM 화면의 내용과 100% 동일해야 한다. 크롤러 전용 텍스트를 따로 추가하거나 변경해서는 안 된다.

2. Puppeteer CPU / 메모리 관리와 캐싱 필수 적용
크롤러가 동시 다발적으로 페이지를 수집할 때마다 Puppeteer 탭을 열면 서버 CPU가 100%로 치솟으며 서버가 다운된다. 반드시 Redis 등을 활용하여 한 번 렌더링된 HTML 결과를 캐싱하고, TTL(예: 24시간)을 두어 동일 페이지 요청은 캐시에서 바로 응답하도록 처리해야 한다.

3. 404 상태 코드 처리
SPA 내부 라우터에서 존재하지 않는 페이지(404)로 이동했을 때, HTTP 상태 코드가 200 OK로 반환되는 'Soft 404' 문제가 자주 발생한다. 프리렌더 서버에서 페이지 내 특정 404 감지 요소가 존재하면 `res.status(404).send(...)`를 명확히 호출하도록 구현해야 한다.

SPA 환경의 검색 노출 누락은 프레임워크를 바꿀 필요 없이 크롤러 분기 처리와 프리렌더링 시스템 구축만으로 완벽하게 극복할 수 있다. 구글 서치 콘솔의 'URL 검사' 도구를 통해 렌더링된 스냅샷이 정상적인 텍스트와 구조로 수집되는지 확인해 보라.
CSR 기술의 우수한 사용자 경험을 유지하면서도 검색 엔진 트래픽을 놓치지 않는 작은 백엔드 조율이 모여서 웹 서비스의 성장을 이끄는 법이다. 이 글의 Nginx 설정 및 Node.js 서버 코드를 참고해 동적 렌더링을 즉시 적용하면 검색 색인 누락 문제를 완전히 해결할 수 있을 것이다.