본 문서는 Framer를 배우는 국내 사용자들이 한글 자료의 부족으로 겪는 어려움을 해결하고자, 공식 블로그의 내용을 한국어로 번역하고 실무에 유용한 정보를 추가했습니다. 프레이머를 사용하는 여러분께 작게나마 도움이 되길 바랍니다.

퍼블리시 오류란 무엇인가요?

퍼블리시 오류는 사이트를 배포할 때 컴포넌트나 페이지에서 문제가 생겨 배포가 중단되는 경우입니다.
게시 오류가 발생하면 “Failed to publish because there is an error on a page.”토스트 알림이 표시됩니다.
이때 Review 버튼이 함께 표시되며, 어떤 컴포넌트가 문제인지 확인할 수 있어요.

자주 발생하는 원인

1. 컴포넌트 빌드 타임아웃

   Framer는 페이지를 만들 때 안에서 사용하는 컴포넌트들을 하나씩 불러와서 조립합니다. 컴포넌트를 불러와서 조립하는 과정에서 어떤 컴포넌트가 너무 느리거나 멈춰 있어서 시간이 다 지나버리면 퍼블리시가 실패합니다.
   예를 들어 웹 검사기(개발자 도구)에 ensureComponentsInLoader: Component loader not updated in time 같은 문구가 나올 수 있어요.

   해결 방법

   다시 퍼블리시 해보세요. 그래도 계속 실패하면, 문제가 될 것 같은 컴포넌트를 찾아서 수정하거나 아예 제거해야 합니다.

   
   

2. 사용하던 컴포넌트가 없어졌어요 (누락 오류)

   예전에 만든 컴포넌트를 쓰고 있는데, 그 컴포넌트를 지우거나 이름을 바꿨거나 혹은 파일이 제대로 불러와지지 않은 경우에도 문제가 생깁니다. Framer에서는 이런 컴포넌트를 레이어 패널에서 회색 상자로 보여줍니다.
   Review 버튼을 눌러보면 바로 어떤 부분이 문제인지 확인할 수 있어요.

   해결 방법

   회색 상자로 표시된 컴포넌트를 다시 불러오거나 새로 만들어서 교체해주면 됩니다.

최적화(Optimization) 오류란?

Framer에서는 사이트를 더 빠르게 보여주기 위해 서버에서 미리 페이지를 만들어두는(Pre-rendering) 방식으로 최적화를 합니다. 그런데 이 서버는 브라우저가 아니기 때문에, 아래와 같은 사용자의 정보를 알 수 없습니다.

• 쿠키(cookie)

• 창 크기(window size)

• 언어(language)

• 또는 window, document, navigator 같은 브라우저 객체

그런데 만약 여러분이 만든 커스텀 코드 컴포넌트나 Override가 이런 정보에 접근하려고 하면, 서버는 그 코드를 실행하지 못하고 최적화 경고(Optimization Warning)를 띄우는 것입니다.

최적화(Optimization) 상태

1. 최적화됨(Optimized)

2. 최적화 경고(Optimization Warning)

3. 최적화 실패(Optimization Error)

Note: Settings → Domains 또는 Settings → Versions에서 최적화 상태를 확인할 수 있습니다.

왜 중요할까요?

• 경고 수준이라도 일부 페이지에서 내용이 늦게 보이거나 비어 보이는 현상이 발생할 수 있습니다.

• 오류가 뜬 경우, 해당 페이지는 SEO, Core Web Vitals 등 품질 지표에 불이익을 받을 수 있어요.

주의해야 할 코드 컴포넌트

최적화 오류의 가장 흔한 원인은 window, document, navigator 같은 브라우저 전용 API를 사용하는 코드 컴포넌트입니다. 서버에서는 브라우저 환경이 아니기 때문에 이 값들이 존재하지 않아요.

이 경우에는 조건부 렌더링을 사용하거나

```js
if (typeof window !== "undefined") {
  // window가 있을 때만 실행되도록 처리
}
```

Framer 가이드에 따라 코드를 리팩토링하여 최적화에 맞게 구성해보세요.
Note: 자세한 가이드는 'How to fix custom code optimization errors'를 참고해주세요.

본 글은 Framer 공식 블로그의 ‘How to debug a publish or optimization warning’을 번역·각색한 콘텐츠입니다.