🚨 [웹사이트 제작 6편] 노션 이미지 엑스박스(깨짐) 오류 해결법

🤔 잘 나오던 노션 이미지가 갑자기 엑스박스로 변한다면?

📌 한 줄 요약: 노션 API의 이미지 URL은 영구적인 주소가 아니기 때문에 시간이 지나면 이미지가 깨질 수 있다. 이 글에서는 노션 이미지 엑스박스 오류의 원인과 빌드 과정에서 이미지를 안정적으로 사용하는 방법을 알아보겠다.

5편까지 따라왔다면 이제 노션에 글을 작성하고, GitHub Actions를 통해 콘텐츠를 자동으로 가져와 웹사이트에 반영하는 구조까지 만들 수 있다.

그런데 여기서 한 가지 문제가 발생할 수 있다.

처음에는 정상적으로 보이던 노션 이미지가 시간이 지나면서 갑자기 엑스박스(깨진 이미지)로 표시되는 것이다.

처음에는 노션에서 이미지를 삭제했거나 파일 자체가 손상된 것으로 생각하기 쉽다.

하지만 문제는 이미지 파일 자체가 아니라 웹사이트에서 사용하고 있는 이미지 URL에 있을 수 있다.

이번 편에서는 노션 이미지가 왜 깨지는지, 그리고 웹사이트에서 이미지를 안정적으로 표시하려면 어떻게 처리해야 하는지 알아본다.

💡 노션 이미지가 깨지는 이유는 '이미지 URL'에 있다

📌 한 줄 요약: Notion API의 이미지 URL은 임시 주소이기 때문에, 그대로 사용하면 시간이 지난 후 이미지가 깨질 수 있다.

노션 페이지의 내용을 API로 가져오면 이미지 블록에 이미지 파일에 접근할 수 있는 URL도 함께 제공된다.

문제는 이 URL이 일반적인 웹사이트의 이미지 주소와 다르다는 것이다.

예를 들어 일반적인 웹사이트에서는 다음과 같은 형태로 이미지 파일을 사용할 수 있다.

이런 경로는 웹사이트에 이미지 파일이 실제로 존재하는 한 계속 사용할 수 있다.

반면 Notion API를 통해 제공되는 이미지 URL은 일정 시간 동안만 유효한 임시 URL 형태로 제공될 수 있다.

따라서 웹사이트가 이 URL을 그대로 사용한다면 처음에는 정상적으로 이미지가 표시되더라도, 시간이 지나 URL이 만료된 이후에는 같은 주소로 이미지를 불러올 수 없게 된다.

결국 브라우저에서는 이미지 대신 엑스박스가 표시된다.

노션 이미지 업로드 → 임시 URL 발급 → 웹사이트에서 URL 사용 → URL 만료 → 이미지 요청 실패 → 엑스박스 표시

여기서 중요한 점은 이미지 파일 자체가 사라진 것이 아니라, 웹사이트가 더 이상 유효하지 않은 이미지 주소를 사용하고 있다는 것이다.

🔎 정말 URL 만료가 원인인지 확인하는 방법

📌 한 줄 요약: 브라우저 개발자 도구에서 이미지 요청 상태와 URL을 확인하면 원인을 파악할 수 있다.

이미지가 깨졌다고 해서 항상 URL 만료가 원인인 것은 아니다.

파일 경로가 잘못되었거나 이미지 다운로드에 실패했거나 접근 권한에 문제가 있을 수도 있다.

따라서 문제가 발생했다면 브라우저의 개발자 도구를 이용해 실제 이미지 요청이 어떻게 처리되고 있는지 확인할 수 있다.

크롬에서 웹사이트를 연 다음 F12 → Network 탭을 선택하고 이미지 요청을 찾아본다.

이미지 요청이 실패했다면 403 Forbidden 등의 상태 코드가 나타날 수 있다.

다만 403이라는 상태 코드만으로 무조건 URL 만료라고 단정해서는 안 된다.

요청한 이미지 URL과 오류 내용을 함께 확인하는 것이 중요하다.

🧩 그렇다면 노션 이미지를 어떻게 안정적으로 사용할까?

📌 한 줄 요약: 이미지가 유효할 때 파일을 다운로드해 웹사이트의 정적 리소스로 저장하면 안정적으로 사용할 수 있다.

해결 방법의 핵심은 간단하다.

만료될 수 있는 노션 이미지 URL을 웹사이트의 최종 이미지 주소로 사용하지 않는 것이다.

대신 빌드 과정에서 노션 API가 제공하는 이미지 URL을 이용해 실제 이미지 파일을 다운로드한다.

그리고 다운로드한 이미지를 웹사이트의 정적 파일로 포함시킨다.

이 과정을 그림으로 보면 훨씬 이해하기 쉽다.

이미지에서 볼 수 있듯이 핵심적인 차이는 노션의 임시 이미지 URL을 최종 웹사이트에서 계속 사용하는 것이 아니라, 빌드할 때 실제 이미지 파일을 웹사이트 안으로 가져오는 것이다.

이렇게 하면 방문자가 웹사이트에 접속할 때마다 만료될 수 있는 노션 이미지 URL에 직접 의존하지 않아도 된다.

⚙️ 실제 자동화 과정에서는 어떻게 처리될까?

📌 한 줄 요약: 빌드 과정에서 노션 이미지와 콘텐츠를 함께 가져와 웹사이트에 자동으로 반영할 수 있다.

5편에서는 GitHub Actions를 이용해 노션 콘텐츠를 가져오고 GitHub 저장소를 업데이트한 뒤 Cloudflare Pages에 배포하는 자동화 구조를 살펴봤다.

여기에 이미지 처리 과정이 포함되면 전체 흐름은 다음과 같이 동작한다.

1. Notion에서 콘텐츠 가져오기
2. 이미지 블록의 이미지 URL 확인
3. 유효한 이미지 URL로 실제 이미지 파일 다운로드
4. 다운로드한 이미지를 웹사이트의 정적 파일로 저장
5. 게시글에서 저장된 이미지 파일을 사용하도록 처리
6. 변경사항을 GitHub에 반영
7. Cloudflare Pages에서 웹사이트 재배포

여기서 중요한 점이 하나 있다.

GitHub Actions 자체가 이미지 깨짐 문제를 해결하는 것은 아니다.

GitHub Actions는 정해진 작업을 자동으로 실행해주는 도구다.

실제로 이미지를 다운로드하고 웹사이트에서 사용할 이미지 경로로 변경하는 작업은 웹사이트를 생성하는 코드에 구현되어 있어야 한다.

따라서 현재 프로젝트에 이러한 이미지 처리 로직이 포함되어 있다면 GitHub Actions를 통해 자동으로 실행할 수 있다.

반대로 이미지 URL을 그대로 사용하는 구조라면 별도의 이미지 다운로드 로직을 추가해야 한다.

🛠️ 이미지 다운로드 기능이 없다면?

📌 한 줄 요약: 이미지 다운로드와 경로 변경 로직을 빌드 과정에 추가해야 한다.

현재 웹사이트 코드가 Notion API에서 받은 이미지 URL을 그대로 HTML에 넣는 방식이라면, URL이 만료된 후 다시 이미지가 깨질 수 있다.

이 경우에는 다음과 같은 과정이 필요하다.

이미지 다운로드 → 정적 파일 저장 → 게시글의 이미지 경로 변경

다만 초보자라고 해서 이 로직을 처음부터 직접 작성해야 하는 것은 아니다.

2편에서 살펴본 AI 바이브코딩을 활용하면 현재 프로젝트의 코드를 AI에게 보여주고 필요한 기능을 추가하는 방법도 있다.

예를 들어 다음과 같이 요청할 수 있다.

AI가 수정한 코드 역시 실제 빌드와 배포 환경에서 테스트해보는 과정이 필요하다.

📊 노션 이미지 URL 직접 사용 vs 이미지 다운로드 방식

📌 한 줄 요약: 이미지 URL을 직접 사용하는 방식보다 파일을 다운로드해 관리하는 방식이 URL 만료 문제에 대응하기에 유리하다.

핵심은 만료될 수 있는 노션 이미지 URL을 최종 웹사이트의 이미지 주소로 계속 사용하지 않는 것이다.

물론 다운로드한 이미지 역시 파일이 삭제되거나 빌드 과정에서 다운로드에 실패하면 문제가 발생할 수 있다.

따라서 이미지 다운로드 방식이라고 해서 모든 이미지 문제가 자동으로 해결되는 것은 아니다.

🚀 이미지 다운로드 방식의 장점

📌 한 줄 요약: 이미지 URL에 대한 의존성을 줄이고 이후 이미지 최적화도 적용하기 쉬워진다.

이미지를 웹사이트 내부에서 관리하면 가장 먼저 이미지 주소의 안정성을 높일 수 있다.

방문자가 웹사이트에 접속할 때마다 노션의 임시 이미지 URL에 의존하지 않고, 웹사이트에서 제공하는 이미지 파일을 사용할 수 있기 때문이다.

또한 이후 이미지 최적화 기능을 추가하기도 쉬워진다.

예를 들어 다음과 같은 작업을 적용할 수 있다.

• 이미지 용량 압축
• WebP 또는 AVIF 변환
• 이미지 크기 최적화
• 썸네일 생성
• 캐싱 설정

다만 이미지를 웹사이트 내부에 저장한다고 해서 자동으로 SEO가 좋아지거나 웹사이트 속도가 빨라지는 것은 아니다.

이미지 로딩 속도는 파일 크기, 포맷, 압축 여부, 캐싱, CDN 구성 등 다양한 요소의 영향을 받는다.

따라서 이번 방식의 가장 직접적인 목적은 노션 이미지 URL 만료로 인한 깨짐 문제를 줄이고 안정적으로 이미지를 제공하는 것이라고 이해하는 것이 정확하다.

🙋‍♂️ 노션 이미지 엑스박스, 궁금했던 점

(👉 질문을 클릭하면 자세한 답변이 펼쳐집니다)

📚 웹사이트 제작 9부작 시리즈 전체 목차

Pixoas에서는 웹사이트 제작을 쉽게 따라 할 수 있도록 9편의 튜토리얼로 쪼개어 연재한다.
차근차근 따라오면 어느새 나만의 개인 웹사이트가 완성되어 있을 것이다.

• 💡 [웹사이트 제작 1편] 유지비 0원? 워드프레스 대신 노션 택한 이유
• 🎨 [웹사이트 제작 2편] AI로 코딩 없이 웹사이트 뼈대 구축하기
• 📝 [웹사이트 제작 3편] 노션을 웹사이트 CMS로 쓰는 법
• ☁️ [웹사이트 제작 4편] Cloudflare Pages로 웹사이트 배포하기
• ⚙️ [웹사이트 제작 5편] 노션 글 자동 반영! 깃허브 액션 연동법
• 🚨 [웹사이트 제작 6편] 노션 이미지 엑스박스 오류 해결 (현재 글)
• 📈 [웹사이트 제작 7편] 검색엔진 등록 & 도메인 연결
• 💰 [웹사이트 제작 8편] 애드센스 승인, 가치 없는 콘텐츠 피하기
• 🤖 [웹사이트 제작 9편] AI로 블로그 방문자 늘리기

이 시리즈는 특정 서비스를 무조건 추천하기 위한 글이 아니다. 내가 직접 여러 방법을 비교하고 구축하면서 선택한 구조를 공유하는 기록에 가깝다. 6편에서는 Notion API 이미지 URL의 특성과 이미지 깨짐 문제, 그리고 빌드 과정에서 이미지를 안정적으로 처리하는 방법을 살펴봤다.

이어지는 7편에서는 완성된 웹사이트가 검색엔진에 제대로 노출될 수 있도록 Google SEO 기본 설정과 개인 도메인 연결 방법을 알아본다.

✅ 마무리 정리

1. Notion API의 이미지 URL은 영구적인 주소가 아니기 때문에 이미지가 깨질 수 있다.
2. 이미지 URL을 그대로 사용하면 URL이 만료된 이후 이미지가 정상적으로 표시되지 않을 수 있다.
3. 이를 해결하려면 빌드 과정에서 이미지를 다운로드해 웹사이트의 정적 리소스로 포함하는 방식을 사용할 수 있다.
4. GitHub Actions는 이러한 작업을 자동으로 실행할 수 있지만, 이미지 다운로드와 경로 변경 로직은 웹사이트 코드에 구현되어 있어야 한다.
5. 이미지를 웹사이트 내부에서 관리하면 이미지 URL 만료 문제를 줄이고 이후 이미지 최적화를 적용하기도 쉬워진다.

💡 참고: Notion API에서 제공되는 이미지 URL의 유효 기간이나 동작 방식은 API 및 서비스 정책에 따라 달라질 수 있습니다. 따라서 특정 시간을 기준으로 “무조건 몇 시간 후 만료된다”고 단정하기보다는 임시 URL이 만료될 수 있다는 점을 기준으로 이해하는 것이 좋습니다.