Cloudflare Pages에서 Pagefind 검색이 동작하지 않았던 이유: 원인은 Rocket Loader였다

Astro.js와 Pagefind로 만든 웹사이트를 Cloudflare Pages에 배포했더니, 로컬에서는 정상적으로 동작하던 검색 기능이 프로덕션 환경에서는 전혀 동작하지 않는 문제를 겪었다.

Pagefind는 정적 사이트용으로 훌륭한 검색 라이브러리이고 Astro.js와도 잘 맞으며 구현도 비교적 간단하다. 그런데 Cloudflare Pages에 배포하는 순간 예상하지 못한 문제가 드러났다.

조사 과정

초기 조사

문제를 인지한 뒤 먼저 아래 항목들을 확인했다.

1. GitHub의 Pagefind 이슈를 확인했지만 Cloudflare Pages와 관련된 유사 사례는 없었다
2. 브라우저 개발자 도구의 콘솔 로그를 봤지만 명확한 에러 메시지는 없었다
3. 네트워크 탭에서 리소스 로딩을 확인했을 때 Pagefind 관련 파일은 정상적으로 불러와지는 것처럼 보였다

이 조사 결과를 보면 문제는 Pagefind 자체보다는 Cloudflare 설정 쪽에 있을 가능성이 높았다.

Cloudflare 설정 조사

Cloudflare에는 다양한 성능 최적화 기능이 있다. 내 사이트에서는 다음 기능을 활성화해 두고 있었다.

1. Cloudflare Zaraz: GA4 같은 분석 도구의 전달을 최적화하는 기능
2. Cloudflare Speed: 사이트 로딩 속도를 높이기 위한 여러 최적화 기능 모음

먼저 Zaraz를 꺼 보고 다시 검증했지만 문제는 해결되지 않았다.

다음으로 Cloudflare Speed 설정을 더 자세히 살펴봤고, 그 과정에서 Rocket Loader 가 켜져 있다는 점을 발견했다.

원인과 해결 방법

Rocket Loader란?

Rocket Loader는 JavaScript 로딩을 최적화하는 Cloudflare 기능이다. 비동기 로딩으로 표시 속도를 개선하지만, JavaScript 실행 순서나 타이밍에 영향을 줄 수 있다.

해결 방법

Cloudflare 대시보드에서 Speed -> Optimization 으로 이동해 Rocket Loader 설정을 끈다.

이 변경을 적용한 뒤 사이트를 다시 불러오자 Pagefind 검색이 정상적으로 동작하기 시작했다.

정리

Astro.js + Pagefind 조합은 정적 사이트에 강력한 검색 기능을 제공하지만, Cloudflare Pages에 호스팅할 때는 Rocket Loader와의 호환성을 주의해야 한다.

비슷한 문제를 겪고 있다면 Rocket Loader를 비활성화하는 것만으로 해결될 가능성이 높다. 또는 Pagefind 초기화 코드를 조정해 Rocket Loader와 공존하도록 만드는 방법도 검토해볼 만하다.