SvelteKit을 Cloudflare로 옮길 때: 2025 배포·검증 체크리스트

SvelteKit을 Cloudflare Workers나 Pages로 옮기는 일은 어댑터 한 줄을 바꾸는 작업으로 끝나지 않는다. 배포 대상의 런타임, 빌드 산출물, 환경 변수와 바인딩, 캐시와 오류 처리까지 한 번에 바뀔 수 있다. 이 글은 새 프로젝트를 처음 만드는 방법이 아니라, 이미 돌아가는 SvelteKit 서비스를 Cloudflare 환경으로 옮긴 뒤 빠뜨리기 쉬운 검증 항목을 정리한다.

출발점은 현재 서비스의 경계를 적는 일이다. 서버 로드 함수와 API 엔드포인트가 어디에 있는지, 파일 시스템이나 Node 전용 모듈에 기대는 코드가 있는지, 이미지 처리나 백그라운드 작업을 어디서 하는지 목록으로 남긴다. Cloudflare에서 실행되는 코드는 일반적인 Node 서버와 동일한 전제를 갖지 않는다. ‘빌드는 통과했다’는 사실과 ‘요청 경로 전체가 같은 방식으로 작동한다’는 사실을 구분해야 한다.

어댑터 전환 뒤에는 svelte.config.js에서 @sveltejs/adapter-cloudflare가 실제로 선택됐는지 확인한다. 설정 파일을 고쳤는데 잠금 파일이나 배포 환경의 의존성이 예전 상태라면 로컬과 원격의 결과가 갈린다. 설치 명령을 복사하는 것보다, CI가 사용한 패키지 버전과 lockfile이 함께 갱신됐는지 보는 편이 더 중요하다. Workers와 Pages 중 어느 운영 모델로 갈지도 이 단계에서 문서로 고정한다.

다음은 산출물 확인이다. 빌드가 끝난 뒤 Cloudflare용 Worker 진입점과 정적 자산이 생성됐는지 보고, Wrangler 설정의 진입점과 자산 디렉터리가 그 결과를 가리키는지 대조한다. 오래된 build 디렉터리나 다른 어댑터의 출력 경로를 배포 대상으로 남겨 두면, 성공한 배포가 이전 사이트를 내보내는 상황이 생긴다. 배포 직전에는 깨끗한 상태에서 빌드하고 생성물 경로를 한 번 더 확인한다.

바인딩은 코드와 플랫폼 사이에서 가장 자주 빠지는 부분이다. KV, D1, R2, Durable Objects, 비밀 값처럼 Cloudflare가 주입하는 값은 SvelteKit의 platform을 통해 접근한다. TypeScript를 쓴다면 App.Platform 선언도 실제 바인딩 이름과 맞춰 둔다. 개발 서버에서 값이 보인다고 끝내지 말고, 미리보기와 원격 환경에서 각각 없는 바인딩일 때 어떤 오류가 나는지 확인해야 한다. 비밀 값은 로그와 클라이언트 번들에 섞이지 않도록 서버 경계에 둔다.

로컬 검증은 화면만 보는 테스트보다 넓어야 한다. 로그인 전후, 동적 경로, 폼 제출, 리다이렉트, 404와 500 페이지, 이미지와 정적 파일, 캐시 헤더를 차례로 확인한다. event.platform을 읽는 핸들러와 서버 엔드포인트는 특히 실제 Workers 호환 런타임에서 점검한다. 외부 API 호출이 있다면 실패·지연·빈 응답에서도 적절한 상태 코드와 사용자 메시지를 돌려주는지 살핀다.

배포 후에는 도메인으로 끝까지 따라가 본다. 첫 요청과 재방문에서 헤더가 어떻게 달라지는지, 보호된 경로가 캐시되지 않는지, 미리보기 URL과 운영 URL이 같은 환경 값을 쓰지 않는지 확인한다. 관측 도구에는 요청 실패와 예외를 남기되 토큰, 쿠키, 개인정보는 기록하지 않는다. 문제를 발견했을 때 이전 배포로 되돌릴 기준과 담당자를 미리 정해 두면 전환 당일의 판단이 훨씬 빨라진다.

마지막 체크리스트는 짧게 유지하는 편이 좋다. 어댑터와 출력 경로, Wrangler 설정, 바인딩 이름, 타입 선언, 로컬·미리보기·운영 검증, 롤백 경로만 매 릴리스마다 확인해도 많은 사고를 줄일 수 있다. 플랫폼 문서는 계속 바뀐다. 배포를 자동화했더라도 의존성 업데이트나 새 바인딩을 넣는 날에는 공식 문서를 다시 확인하고, 실제 요청으로 검증한 결과를 배포 기록에 남기자.

대표 출처

https://svelte.dev/docs/kit/adapter-cloudflare
https://developers.cloudflare.com/workers/framework-guides/web-apps/sveltekit/