Webflow 사이트를 미러링할 때 깨지는 현상과 해결 방법

Webflow의 코드 내보내기(code export)에는 두 가지 문제가 있습니다. 첫째, 유료 Workspace 플랜에서만 사용할 수 있고, 둘째, 비용을 지불하더라도 CMS 콘텐츠가 포함되지 않습니다. 컬렉션 목록은 빈 상태로 내보내지고, 컬렉션 페이지는 내용물이 없는 상태로 내보내집니다. 만약 사이트에 블로그가 있다면, 내보낸 결과물은 블로그가 없는 사이트입니다. 또한, Webflow 자체 문서에 따르면 폼(Forms)과 검색 기능도 내보낸 코드에서 비활성화됩니다.

한편, 실제로 게시된(published) 사이트는 CDN에 위치하며 완전히 렌더링되어 있습니다. 모든 CMS 페이지는 실제 HTML로 구성되어 있습니다. 따라서 wget --mirror 명령어를 사용하면 이 모든 것을 문제없이 가져올 수 있습니다.

하지만 wget이 제공하는 결과물은 배포 가능한 형태가 아닙니다. 제가 실제로 운영 중인 Webflow 사이트를 이 방식으로 마이그레이션(migrate)하면서 모두가 겪는 동일한 다섯 가지 오류를 만났기 때문에, 저는 그 해결책들을 Claude Code skill로 만들어 전체 워크플로우를 실행하도록 했습니다. 이 글은 그 다섯 가지 오류에 대한 내용인데, 이는 스킬을 사용하든 안 하든 유용하며 Framer나 Squarespace 등 다른 도메인 이름을 가진 사이트에도 적용됩니다.

설정: 미러링 자체

가장 중요한 wget 명령어는 Webflow가 에셋(assets)을 별도의 CDN 도메인에서 제공하기 때문에, wget에게 이를 따라가라고 알려줘야 한다는 점입니다:

wget --mirror --convert-links --adjust-extension \
  --page-requisites --span-hosts \
  --domains=yourdomain.com,cdn.prod.website-files.com \
...

이 명령어는 모든 페이지와 해당 페이지가 참조하는 CSS, JS, 이미지, 폰트 등을 다운로드하고 URL을 상대 경로로 재작성합니다. 완성된 것처럼 보입니다. 하지만 약 90%만 완료되었고, 나머지 10%는 페이지가 공백으로 렌더링될 때까지 눈에 띄지 않습니다.

오류 1: 페이지가 공백으로 렌더링되고 콘솔에 'integrity' 메시지가 표시됨

원인은 미묘합니다. Webflow는 <link> 및 <script> 태그에 SHA-384 SRI 해시를 포함하여 배포합니다. wget의 --convert-links는 다운로드된 CSS 파일 내부의 URL을 재작성하는데, 이 과정이 파일 바이트를 변경시키고, 그 결과 SRI 해시가 더 이상 일치하지 않게 됩니다. 따라서 브라우저는 스타일시트를 적용하는 것을 조용히 거부합니다. 파일은 제자리에 있습니다. 브라우저가 건드리지 않습니다.

해결책은 무결성 속성(integrity attributes)과 (그것과 함께 전송되는) crossorigin을 제거하는 것입니다:

sed -i '' -E 's/ integrity="[^"]*"//g; s/ crossorigin="[^"]*"//g' *.html

이것은

깨짐 현상 4: 히어로 이미지 누락 (인라인 background-image)

--page-requisites는 src 및 href 속성만 처리합니다. 인라인 스타일은 파싱하지 못하기 때문에, 일반적인 Webflow 마케팅 사이트에서 히어로 이미지를 포함하는 모든 background-image:url(...) 에셋이 단순히 다운로드되지 않습니다. HTML에서 CDN으로 참조되는 background-image:url(을 검색(Grep)하여 추출하고 가져와야 합니다. 이 깨짐 현상 안에 또 다른 보너스 깨짐 현상이 있습니다: --convert-links는 이러한 인라인 URL들을 중첩된 따옴표 쓰레기(nested-quote garbage)로 망가뜨리므로, 별도의 sed 처리가 필요합니다.

깨짐 현상 5: 재구성 후 발생하는 폰트 404 오류

Webflow는 Webflow의 디렉토리 구조를 가정하여 CSS에서 폰트를 url(../font.ttf)와 같이 참조합니다. 이 경로가 제대로 작동하는 순간, 즉 이를 합리적인 assets/css/, assets/js/, assets/images/ 구조로 통합하는 순간, 해당 상대 경로는 잘못된 디렉토리를 가리키게 됩니다. CSS를 한 번의 정규표현식(regex) 패스로 재작성하면 이 문제를 해결할 수 있습니다.

모든 것을 구동시키는 기술

저는 전체 과정—미러링, 통합, 재작성, 그리고 다섯 가지 수정 사항과 브라우저 내 검증 패스, 배포까지—을 오픈 소스 Claude Code 스킬로 패키징했습니다:

npx skills add stevysmith/website-builder-migrate-skill

그런 다음 /website-builder-migrate https://yourdomain.com/이 7단계 워크플로우를 실행합니다. 이 도구는 플랫폼에 구애받지 않으며, 각 플랫폼별 참고 사항을 제공합니다: Framer (React SPA, Hydration 검증), Squarespace (서버 측 이미지 변환), Carrd (사소함, 단일 파일), 그리고 Wix의 경우 솔직히 말씀드리자면: 클라이언트 렌더링이 많이 된 Wix 사이트는 미러링이 잘 되지 않으므로, 정적 템플릿 전용으로 간주해야 합니다.

저장소(Repo): https://github.com/stevysmith/website-builder-migrate-skill

DNS 이전 전에 비공개 URL에서 검증하기

마이그레이션된 사이트는 공개적으로 어떤 변경이 생기기 전에 원본과 비교하여 확인해야 합니다. 고백하자면, 저는 Stacktree를 구축했는데, 이 도구는 바로 이 단계를 위해 추가한 배포 대상이기 때문입니다. 왜냐하면 계정이 필요 없는 유일한 도구이기 때문입니다. 마이그레이션된 폴더는 한 줄의 명령어로 비공개적이고 추측 불가능한 미리 보기 URL에 게시됩니다:

(cd site && zip -qr ../site.zip .) && curl -F "file=@site.zip" https://api.stacktr.ee/sites

이 미리 보기 링크는 24시간 동안 유지되므로, 원본과 나란히 있는 모든 페이지를 클릭하며 확인하기에 충분합니다. 이 링크가 만료되면 원하는 곳 어디든 배포할 수 있습니다. 해당 스킬의 문서에는 Render, Netlify, Vercel도 다루고 있으며, Stacktree를 유지하는 것은 무료 티어만 거리가 멉니다.

모든 경로에서 깨지는 것들

폼(Webflow 백엔드가 필요하므로 Formspree나 Basin으로 교체해야 함), 네이티브 사이트 검색(Pagefind가 정적 사이트에 적합한 답변임), 라이브 CMS 업데이트(미러는 스냅샷이므로 콘텐츠가 변경되면 이 과정을 다시 실행해야 함)은 깨집니다. 반복할 가치가 있습니다: Webflow의 공식 유료 내보내기 기능도 폼과 검색을 비활성화하며, CMS 페이지 자체를 제공하지 않습니다. 미러는 다운그레이드가 아닙니다. 정적 사이트의 경우 더 완벽한 복사본입니다.

만약 이 목록에 없는 깨짐 현상을 발견했다면, 해당 레포지토리(repo)에 이슈를 열어주세요. 이 목록은 정확히 그런 과정을 통해 다섯 개로 늘어났습니다.