Pagefind 한국어 검색, 'stemming 없음' 경고를 무시하면 안 되는 이유

정적 블로그에 Pagefind를 붙인 뒤 npm run build를 돌리면, 성공 메시지 바로 위에 노란 느낌의 안내가 한 줄 뜬다. “Pagefind doesn’t support stemming for the language ko.” 처음엔 경고처럼 보이지만 빌드는 그대로 통과한다. 그래서 무시하기 쉽다. 문제는 방문자가 검색창에 활용형·조사가 섞인 한국어를 넣었을 때, 영어 블로그와 같은 수준의 관대함을 기대하면 실망한다는 점이다.

사실: 로그가 말해 주는 것과 숫자

2026-08-11 로컬 실측 기준, astro build && pagefind --site dist/ 파이프라인은 약 4초 안에 끝났고 Pagefind 인덱싱 단계만 0.673초였다. 인덱서는 data-pagefind-body 요소를 찾지 못해 전체 <body>를 색인했다. 한국어 페이지는 ko 하나로 집계됐고, 191페이지·40,345단어가 인덱스에 들어갔다. dist/pagefind/pagefind.js는 약 45KB였다.

같은 로그에 stemming 미지원이 두 번 반복된다. Pagefind 문서상 stemming은 영어처럼 run/running/ran을 묶어 주는 형태소 축약이다. 한국어는 조사·어미 변화가 훨씬 촘촘한데, 현재 Pagefind는 이를 자동으로 묶지 않는다. 검색은 되지만, 어근 단위 매칭은 기대하지 말라는 뜻이다.

이유: 정적 검색의 트레이드오프

Pagefind를 쓰는 이유는 서버리스·Workers 환경에서 DB 없이 풀텍스트 검색을 얻기 위해서다. 빌드 타임에 HTML을 긁고 WASM으로 질의하니 런타임 비용이 거의 없다. 대신 언어별 전처리 품질은 Pagefind가 지원하는 언어 목록에 묶인다. 한국어 블로그는 콘텐츠·UI가 한글이 중심이므로, 영어 stemming이 있는 사이트와 체감 품질 격차가 바로 드러난다.

예를 들어 본문에만 「배포」가 있고 제목에 「배포했다」가 있을 때, 방문자가 「배포했」로 검색하면 매칭이 애매해질 수 있다. 반대로 고유명사·영문 슬러그(Cloudflare, Astro)는 오히려 잘 맞는다. 이 블로그처럼 IT 회고와 고유 기술명이 섞인 글에서는 키워드 일치 검색에 가깝고, 자연어 질의 엔진은 아니다.

평가: 어디에 쓰고 어디에 안 쓰는지

쓸 만한 경우: 글 수가 수백 편 이하이고, 독자가 제목·태그에 나온 고정어로 찾는 패턴이 많을 때. 태그에 장애회고, Cloudflare처럼 검색 의도가 분명한 키워드를 넣으면 체감이 올라간다.

안 맞는 경우: 「~하는 방법」「~했을 때」처럼 구어체 질문을 그대로 넣는 UX를 기대할 때. 그때는 외부 검색 API나 한국어 형태소 분석이 붙은 별도 엔진을 검토해야 한다. Pagefind를 유지하더라도 사이트 내 검색은 보조 수단으로 두고, 카테고리·태그 내비게이션을 주 경로로 설계하는 편이 낫다.

운영 측면에서는 data-pagefind-body로 본문 영역만 색인 범위를 좁히는 것도 고려할 만하다. 지금은 헤더·푸터까지 포함되므로, 공통 문구가 검색 결과를 희석할 수 있다. 다만 Astro 레이아웃에 속성을 추가하는 작업이 필요하고, 빌드 후 색인 단어 수가 줄어드는지 다시 실측해야 한다.

부연: 다음에 볼 체크 포인트

배포 전 스모크 테스트에 검색 케이스를 넣는다. (1) 기술 고유명사 1개, (2) 한국어 제목의 핵심 명사 1개, (3) 활용형으로 변형한 쿼리 1개. 세 번째가 실패해도 빌드는 통과하므로, CI가 아니라 수동·스크립트 검증이 필요하다. Cloudflare Workers로 pagefind/ 정적 경로가 200으로 서빙되는지는 별도로 Network 탭에서 확인한다(기존 trailing slash 글 참고).

한국어 stemming 미지원은 장애가 아니라 명시된 한계다. 로그 한 줄을 건너뛰면, 독자 불만은 검색 UI로 돌아온다. 시니어 IT 실무자 시각으로는 「검색 붙였다」와 「한국어로 잘 찾아진다」는 다른 완료 조건이다.

출처

내부 실측: npm run build && pagefind --site dist/ (2026-08-11) — 191 pages, 40345 words, ko stemming 경고, pagefind.js 약 45KB
Pagefind documentation — languages — 지원 언어·stemming 범위 (열람: 2026-08-11)
Notion 시드: «디버깅 프롬프트 모음» — Workers·서버리스 제한 구간 점검 관점만 차용 (민감 정보 제외)