Astro 블로그에 Pagefind 검색 추가하기: 무료·고속·한국어 지원 완벽 가이드

블로그 글이 점점 많아지면서 독자에게서 이런 메시지를 자주 받았습니다. “검색 기능을 추가해 주실 수 있나요? 예전에 XX에 관한 글을 쓰신 것 같은데 한참 찾아도 못 찾겠어요.”

그동안 검색 기능 추가를 계속 미뤘습니다. Algolia는 너무 비쌌고 개인 블로그에서 매달 수십 달러를 내기는 부담스러웠습니다. Elasticsearch를 직접 구축하자니 손이 너무 많이 갔습니다. 그러다 설정이 간단하고 인덱스 파일은 수십 KB에 불과하며 완전 무료이고 한국어도 기본 지원하는 Pagefind를 발견했습니다.

Pagefind란 무엇일까요? 간단히 말하면 정적 사이트 전용 검색 엔진입니다. 빌드할 때 검색 인덱스를 자동으로 생성하고 검색은 전부 브라우저에서 처리하므로 백엔드 서버나 서드파티 API가 필요 없습니다. 무엇보다 완전 무료이고 매우 빠르며 설정도 아주 간단합니다.

이 글에서는 다음 내용을 단계별로 설명합니다.

• 개인 블로그에는 왜 Algolia보다 Pagefind가 더 적합한가
• Pagefind 설정을 10분 안에 끝내는 방법
• 고급 최적화와 한국어 검색 튜닝
• 자주 발생하는 문제와 해결 방법

Astro로 블로그를 만들었고 비용 없이 검색 기능을 추가하고 싶다면 이 글이 도움이 될 것입니다.

왜 Pagefind를 선택해야 할까요?

블로그에 검색 기능을 추가하기로 결정하기 전에 시중의 주요 솔루션을 비교했습니다. 최종적으로 Pagefind를 고른 이유는 크게 비용, 개인정보 보호, 성능 세 가지입니다.

정적 검색만의 장점

Pagefind는 ‘정적 검색’ 방식입니다. 검색 인덱스를 빌드할 때 생성해 사이트와 함께 배포하고 브라우저에서 검색을 처리합니다. 이 방식에는 몇 가지 뚜렷한 장점이 있습니다.

완전 무료입니다. Algolia처럼 검색 횟수에 따라 요금을 부과하지 않습니다. 블로그 방문자가 아무리 많아져도 검색 기능 때문에 비용이 들지 않습니다.

개인정보를 보호합니다. 사용자의 검색 내용이 서드파티 서버로 전송되지 않고 모든 검색이 로컬에서 처리됩니다. 개인정보를 중시하는 독자에게 특히 중요한 부분입니다.

백엔드가 필요 없습니다. 기존 검색 솔루션은 서버와 데이터베이스를 유지하고 고가용성까지 고려해야 합니다. Pagefind는 완전한 정적 방식으로 CDN에 배포되며 웹페이지만큼 안정적입니다.

필요할 때만 로드합니다. Pagefind 인덱스는 여러 작은 조각으로 나뉘며 사용자가 검색을 시작할 때 필요한 부분만 불러옵니다. 첫 화면 로딩에는 영향을 주지 않아 사용자 경험이 좋습니다.

Pagefind와 Algolia 비교

빠르게 비교할 수 있도록 표로 정리했습니다.

솔직히 Algolia는 매우 강력합니다. 검색 속도와 오타 허용 능력, 분석 기능은 모두 최고 수준입니다. 하지만 개인 블로그에는 지나치게 큰 도구입니다. 더 중요한 문제는 블로그 트래픽이 늘어나면 Algolia 비용도 빠르게 증가한다는 점입니다.

실제 사례와 데이터

Pagefind의 성능은 매우 뛰어납니다. BryceWray.com의 실제 테스트에 따르면 10,000페이지 규모의 사이트에서 Pagefind가 생성한 검색 인덱스는 300KB도 되지 않았습니다. 대부분의 블로그 인덱스는 약 100KB에 불과합니다.

Pagefind 공식 테스트 결과는 더욱 놀랍습니다. 19페이지 사이트의 인덱싱에 0.043초밖에 걸리지 않았습니다. Rust로 작성되어 빌드 속도가 매우 빠르기 때문에 수천 페이지짜리 블로그도 몇 초면 처리합니다.

실제 사용 사례로 Astro 공식 문서 사이트인 Starlight에는 기본 검색 솔루션으로 Pagefind가 내장되어 있습니다. Astro 공식 프로젝트에서도 선택한 도구라면 충분히 신뢰할 만합니다.

5단계로 Pagefind 설정 끝내기

이론은 여기까지입니다. 이제 Pagefind를 직접 설정해 보겠습니다. 정말 10분이면 충분합니다.

1단계: 의존성 설치

먼저 npm 패키지 두 개를 설치합니다.

npm install astro-pagefind pagefind

왜 패키지를 두 개나 설치해야 하는지 궁금할 수 있습니다.

astro-pagefind는 빌드할 때 Pagefind를 자동으로 실행하는 Astro 통합입니다. pagefind는 검색 UI와 API가 포함된 핵심 라이브러리입니다. 뒤에서 pagefind 리소스를 직접 참조하므로 둘 다 설치해야 합니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

2단계: astro.config.mjs 설정

astro.config.mjs 파일을 열고 Pagefind 통합을 추가합니다.

import { defineConfig } from 'astro/config';
import pagefind from 'astro-pagefind';

export default defineConfig({
  integrations: [pagefind()],
});

이게 전부입니다! 이 코드를 추가하면 npm run build를 실행할 때마다 Pagefind가 사이트 콘텐츠를 자동으로 인덱싱합니다.

3단계: 검색 컴포넌트 만들기

src/components/ 디렉터리에 Search.astro 컴포넌트를 만듭니다.

---
// src/components/Search.astro
---

<link href="/pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js"></script>
<div id="search"></div>

<script>
  window.addEventListener('DOMContentLoaded', () => {
    new PagefindUI({
      element: "#search",
      showSubResults: true,
      showImages: false
    });
  });
</script>

여기에는 몇 가지 설정 항목이 있습니다.

• element: 검색 UI를 마운트할 DOM 요소 지정
• showSubResults: 일치한 문단과 같은 하위 결과 표시
• showImages: 페이지 썸네일 표시 여부. 보통 더 빠른 로딩을 위해 끕니다

사이트에서 ViewTransitions를 사용한다면 페이지를 전환할 때 검색 컴포넌트가 다시 초기화되지 않도록 transition:persist 지시어를 추가해야 합니다.

<div id="search" transition:persist></div>

4단계: 페이지에서 검색 컴포넌트 사용하기

검색 컴포넌트를 사용하는 방법은 두 가지입니다.

방법 1: 내비게이션 바에 삽입

Header.astro 또는 Navbar.astro에서 바로 가져옵니다.

---
import Search from '../components/Search.astro';
---

<header>
  <nav>
    <!-- 내비게이션 링크 -->
  </nav>
  <Search />
</header>

방법 2: 별도의 검색 페이지 생성

src/pages/search.astro를 만듭니다.

---
import Layout from '../layouts/Layout.astro';
import Search from '../components/Search.astro';
---

<Layout title="검색">
  <main>
    <h1>글 검색</h1>
    <Search />
  </main>
</Layout>

그런 다음 내비게이션 바에 /search 페이지로 이동하는 링크를 추가합니다. 개인적으로는 내비게이션 바가 복잡해지지 않는 이 방법을 더 선호합니다.

5단계: 빌드와 테스트

설정이 끝났습니다! 이제 빌드 명령을 실행합니다.

npm run build

모든 것이 정상이라면 다음과 비슷한 출력이 표시됩니다.

Running Pagefind...
Indexed 42 pages
Indexed 3,582 words
Created 5 index chunks
Finished in 0.234 seconds

로컬에서 결과를 테스트하려면 다음 명령을 실행합니다.

npm run build && npx pagefind --site dist --serve

브라우저에서 http://localhost:1234에 접속해 검색 기능이 작동하는지 확인합니다.

검색창이 나타나고 키워드를 입력했을 때 결과가 반환된다면 설정에 성공한 것입니다!

고급 설정과 최적화

기본 설정만 마쳐도 검색 기능을 사용할 수 있습니다. 하지만 검색을 더 정확하고 빠르게 만들고 필요에 맞추고 싶다면 몇 가지 고급 최적화를 적용할 수 있습니다.

인덱싱 범위 정밀 제어

기본적으로 Pagefind는 <body> 태그 안의 모든 콘텐츠를 인덱싱합니다. 따라서 내비게이션 바, 사이드바, 바닥글의 텍스트까지 인덱스에 포함되어 검색 결과가 부정확해질 수 있습니다.

예를 들어 바닥글에 ‘소개’ 문구가 있으면 사용자가 ‘작성자’를 검색할 때 모든 페이지가 결과에 나타날 수 있습니다. 모든 페이지에 같은 바닥글이 있기 때문입니다.

해결 방법은 data-pagefind-body 속성으로 인덱싱할 영역을 지정하는 것입니다.

<body>
  <nav data-pagefind-ignore>
    <!-- 내비게이션 바는 인덱싱하지 않음 -->
  </nav>

  <main data-pagefind-body>
    <!-- 본문 콘텐츠만 인덱싱 -->
    <article>
      <h1>글 제목</h1>
      <p>글 내용...</p>
    </article>
  </main>

  <aside data-pagefind-ignore>
    <!-- 사이드바는 인덱싱하지 않음 -->
  </aside>

  <footer data-pagefind-ignore>
    <!-- 바닥글은 인덱싱하지 않음 -->
  </footer>
</body>

data-pagefind-body를 사용하면 Pagefind는 이 요소 내부의 콘텐츠만 인덱싱하고 나머지 영역은 자동으로 무시합니다. 일부 요소만 제외하고 싶다면 data-pagefind-ignore를 사용하면 됩니다.

이렇게 하면 두 가지 장점이 있습니다.

1. 검색 정확도 향상 - 본문만 검색하므로 관련 없는 콘텐츠의 방해를 받지 않습니다
2. 인덱스 축소 - 반복되는 내비게이션 바와 바닥글을 제거해 인덱스 크기를 30~50% 줄입니다

메타데이터와 제목 사용자 지정

Pagefind는 기본적으로 페이지의 첫 번째 <h1>을 검색 결과 제목으로 선택하고 첫 몇 문단을 요약문으로 사용합니다. 하지만 때로는 정확하지 않을 수 있습니다.

data-pagefind-meta로 직접 지정할 수 있습니다.

<!-- 기본 제목 덮어쓰기 -->
<h1 data-pagefind-meta="title">Astro 검색 기능 구현 가이드</h1>

<!-- 요약 지정 -->
<p data-pagefind-meta="description">
  Astro 블로그에 Pagefind 검색을 추가하는 방법과 전체 설정 단계, 한국어 최적화 방법을 설명합니다.
</p>

<!-- 이미지 지정 -->
<img data-pagefind-meta="image[src]" src="/cover.jpg" alt="표지 이미지">

검색 가중치 조정

제목과 일치한 결과를 앞쪽에 표시하고 싶다면 가중치를 조정할 수 있습니다.

<h1 data-pagefind-weight="10.0">글 제목</h1>
<p data-pagefind-weight="1.0">본문 내용</p>

가중치가 높을수록 해당 요소와 일치한 결과가 상위에 표시됩니다. 기본 가중치는 1.0이며 제목은 보통 5.0~10.0으로 설정합니다.

한국어 검색 테스트

Pagefind가 해외에서 만든 도구라 한국어 지원이 괜찮을지 걱정할 수 있습니다.

다행히 Pagefind는 한국어를 포함한 다국어를 기본 지원하며 별도 설정 없이 사용할 수 있습니다. 실제 테스트 결과도 좋았습니다.

• 단어 분리 정확도: ‘Astro 검색’을 검색하면 ‘Astro’, ‘검색’, ‘Astro 검색 기능’과 일치합니다
• 퍼지 매칭: ‘블로그 검색’을 검색하면 ‘블로그에 검색 추가’, ‘블로그 검색 기능’과 일치합니다
• 로마자 표기 미지원: 유일한 한계로, ‘beullogeu’를 검색해도 ‘블로그’를 찾지 못합니다. 하지만 기술 블로그에는 큰 영향이 없습니다

검색 UI 사용자 지정

Pagefind의 기본 UI만으로도 충분하지만 스타일을 바꾸거나 필터를 추가하는 등 세밀하게 조정하고 싶다면 JavaScript API를 사용할 수 있습니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

// Pagefind 초기화
const pagefind = await import("/pagefind/pagefind.js");

// 검색 실행
const search = await pagefind.search("Astro");

// 결과 상세 정보 가져오기
const results = await Promise.all(
  search.results.map(r => r.data())
);

// 사용자 지정 UI 렌더링
results.forEach(result => {
  console.log(result.url);      // 페이지 URL
  console.log(result.meta.title); // 제목
  console.log(result.excerpt);   // 요약
});

API를 사용하면 UI를 완전히 제어해 디자인 시스템과 자연스럽게 통합할 수 있습니다. 단점은 렌더링 로직을 직접 작성해야 한다는 점입니다. 대부분의 경우에는 기본 UI로도 충분합니다.

자주 발생하는 문제와 해결 방법

설정 과정에서 몇 가지 사소한 문제를 만날 수 있습니다. 가장 자주 발생하는 문제와 해결 방법을 정리했습니다.

문제 1: 검색 결과에 잘못된 제목이나 요약이 표시됨

증상: 검색 결과 제목이 글 제목과 다르거나 요약에 내비게이션 바의 문구가 표시됩니다.

원인: Pagefind는 기본적으로 첫 번째 <h1>과 첫 몇 문단을 선택합니다. 페이지 구조가 표준과 다르면 잘못된 요소를 선택할 수 있습니다.

해결 방법: data-pagefind-meta로 직접 지정합니다.

---
// BlogPost.astro 레이아웃 파일
const { title, description } = Astro.props;
---

<article>
  <h1 data-pagefind-meta="title">{title}</h1>
  <p data-pagefind-meta="description">{description}</p>
  <!-- 기타 콘텐츠 -->
</article>

문제 2: ViewTransitions 때문에 검색이 작동하지 않음

증상: Astro ViewTransitions를 사용할 때 검색 페이지로 이동하면 검색창이 작동하지 않습니다.

원인: ViewTransitions가 스크립트를 다시 실행하지만 DOM은 이미 비워져 초기화에 실패합니다.

해결 방법: 검색 컨테이너에 transition:persist 지시어를 추가합니다.

<div id="search" transition:persist></div>

이 지시어는 페이지를 전환할 때 Astro가 해당 요소를 다시 렌더링하지 않고 유지하도록 합니다.

문제 3: 빌드할 때 pagefind 명령을 찾지 못함

증상: npm run build를 실행하면 pagefind: command not found 오류가 발생합니다.

원인: astro-pagefind만 설치하고 핵심 패키지인 pagefind를 설치하지 않았습니다.

해결 방법: 두 패키지를 모두 설치합니다.

npm install astro-pagefind pagefind

그래도 해결되지 않으면 astro.config.mjs에 통합이 올바르게 추가되었는지 확인합니다.

문제 4: 배포 후 검색 기능에서 404 발생

증상: 로컬 테스트에서는 정상적으로 작동하지만 Cloudflare Pages 또는 Netlify에 배포한 뒤 검색하면 브라우저에 404 오류가 발생하며 /pagefind/pagefind.js를 찾지 못합니다.

원인: 빌드 결과물에 pagefind 폴더가 없습니다. 빌드 명령 설정이 잘못되었을 수 있습니다.

해결 방법: 빌드 명령에 Pagefind 인덱싱 단계가 포함되어 있는지 확인합니다. astro-pagefind 통합을 사용했다면 자동으로 처리되어야 합니다. 그래도 작동하지 않으면 package.json을 직접 수정합니다.

{
  "scripts": {
    "build": "astro build && npx pagefind --site dist"
  }
}

배포할 때 이 build 명령을 사용하는지 확인합니다.

문제 5: CSP 오류 또는 너무 큰 인덱스

CSP(Content Security Policy) 오류

브라우저 콘솔에 Refused to load WebAssembly 오류가 표시된다면 Pagefind가 WebAssembly를 사용하기 때문입니다. CSP 헤더에 wasm-unsafe-eval 지시어를 추가해야 합니다.

Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'

Cloudflare Pages를 사용한다면 _headers 파일에 다음 내용을 추가합니다.

/*
  Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'; default-src 'self'

너무 큰 인덱스

빌드 후 pagefind 폴더가 몇 MB에 달한다면 필요 없는 콘텐츠까지 인덱싱했을 가능성이 큽니다. 인덱싱 범위를 정밀하게 지정해 본문만 인덱싱하면 해결할 수 있습니다.

<body>
  <nav data-pagefind-ignore>...</nav>
  <main data-pagefind-body>
    <!-- 이 영역만 인덱싱됩니다 -->
  </main>
  <footer data-pagefind-ignore>...</footer>
</body>

이렇게 하면 인덱스 크기를 30~50% 줄일 수 있습니다. 또한 Pagefind는 필요할 때만 로드하므로 사용자는 일치하는 키워드에 해당하는 인덱스 부분만 다운로드하고 실제 로딩 용량도 작습니다.

실제 적용 사례와 모범 사례

설정을 마친 뒤 검색 기능을 더 완성도 있게 만드는 몇 가지 최적화 방법이 있습니다.

인덱스 품질 모니터링

Pagefind는 빌드할 때마다 인덱스 통계를 출력합니다. 다음 지표를 확인하세요.

Running Pagefind...
Indexed 42 pages       ← 인덱싱된 페이지 수
Indexed 3,582 words    ← 전체 단어 수
Created 5 index chunks ← 인덱스 조각 수
Finished in 0.234 seconds

핵심 지표 해석:

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

• pages는 글 수와 같아야 합니다. 더 적다면 일부 페이지가 인덱싱되지 않은 것이므로 data-pagefind-ignore 때문에 제외되었는지 확인합니다
• index chunks는 적을수록 인덱스가 작다는 뜻입니다. 보통 1,000~2,000페이지마다 하나의 chunk로 나뉩니다
• 빌드 시간이 5초를 넘는다면 콘텐츠가 너무 많거나 인덱싱 범위가 너무 넓다는 뜻이므로 최적화를 고려합니다

배포 체크리스트

프로덕션 환경에 배포하기 전에 다음 항목을 확인합니다.

1. pagefind 폴더가 있는지 확인

ls dist/pagefind

pagefind.js, pagefind-ui.js, pagefind-ui.css 등의 파일이 보여야 합니다.

2. 검색 기능 테스트

• 자주 쓰는 키워드를 검색해 결과가 반환되는지 확인
• 한국어 단어를 검색해 단어 분리가 올바른지 확인
• 존재하지 않는 단어를 검색해 ‘결과 없음’ 안내가 표시되는지 확인

3. 인덱스 크기 확인

du -sh dist/pagefind

일반적으로 50KB~500KB여야 합니다. 1MB가 넘으면 인덱싱 범위를 최적화하는 것을 고려하세요.

4. 모바일 테스트
휴대전화에서 사이트를 열고 검색 기능이 정상적으로 작동하는지 테스트합니다. Pagefind 기본 UI는 반응형이지만 사용자 지정 UI는 직접 대응해야 합니다.

SEO 고려 사항

검색 페이지 자체는 검색 엔진에 노출할 필요가 없으므로 search.astro에 noindex를 추가하는 것이 좋습니다.

<head>
  <meta name="robots" content="noindex, follow">
</head>

이렇게 하면 검색 엔진이 검색 페이지는 인덱싱하지 않지만 페이지 안의 링크는 따라갑니다. 추천 글이 있을 때 유용합니다.

성능 최적화 방법

1. 검색 컴포넌트 지연 로딩

검색창이 내비게이션 바에 있지만 대부분의 사용자가 이용하지 않는다면 지연 로딩을 고려할 수 있습니다.

<div id="search"></div>

<script>
  // 사용자가 검색 아이콘을 클릭할 때만 Pagefind 로드
  document.getElementById('search-icon').addEventListener('click', async () => {
    const pagefind = await import("/pagefind/pagefind-ui.js");
    new PagefindUI({ element: "#search" });
  });
</script>

이렇게 하면 첫 화면에서 Pagefind 관련 리소스를 로드하지 않아 성능이 향상됩니다.

2. CDN 가속

Pagefind 인덱스 파일은 모두 정적입니다. CDN에 캐시되는지 확인합니다.

# _headers (Cloudflare Pages)
/pagefind/*
  Cache-Control: public, max-age=31536000, immutable

3. 프리로드 최적화

사용자가 검색 페이지에 머무르면 자주 쓰는 키워드의 인덱스를 미리 불러올 수 있습니다.

const pagefind = await import("/pagefind/pagefind.js");

// 인기 키워드 인덱스 미리 불러오기
pagefind.preload("Astro");
pagefind.preload("React");

결론

지금까지의 내용을 요약하면 Pagefind는 Astro 블로그에 검색 기능을 추가할 때 가장 좋은 선택입니다. 완전 무료이고 설정이 간단하며 성능이 뛰어나고 한국어도 지원합니다.

연간 수백 달러가 드는 Algolia와 비교하면 Pagefind로 비용을 크게 아낄 수 있습니다. 서버 유지 관리나 API 설정도 필요 없어 설치 후 바로 사용할 수 있습니다.

블로그에 검색 기능을 추가할지 아직 망설이고 있다면 10분만 투자해 Pagefind를 사용해 보세요. 설정 과정은 생각보다 훨씬 간단하고 결과는 기대 이상일 것입니다.

마지막으로 설정 과정에서 문제가 생겼다면 댓글로 알려 주세요. 이미 Pagefind 설정에 성공했다면 사용 경험도 공유해 주세요!

더 읽어보기:

• Pagefind 공식 문서
• Astro Starlight 검색 가이드
• astro-pagefind GitHub 저장소