노션을 Headless CMS로 쓸 때 마주치는 1시간 만료 이미지 이슈(AWS S3 Presigned URL)와 완벽한 해결법

Astro와 노션(Notion)을 결합한 Headless CMS 파이프라인은 에디터의 작성 편의성과 정적 사이트(SSG)의 압도적인 웹 성능을 동시에 잡을 수 있는 매력적인 아키텍처입니다.
연동을 마치고 노션에서 글을 쓰고 배포를 누르면, 웹사이트에 제목과 본문뿐만 아니라 업로드한 이미지까지 시각적으로 완벽하게 노출됩니다.
하지만 기쁨도 잠시, 발행 후 정확히 1시간 정도가 지나면 멀쩡하던 이미지가 브라우저에서 물음표 아이콘(엑스박스)으로 깨지며 사라지는 기현상을 마주하게 됩니다.
노션을 CMS로 구축할 때 99%의 개발자가 겪게 되는 이 치명적인 이미지 만료 문제의 원인과, Astro 빌드 타임에서 이를 영구적으로 해결한 실무 파이프라인을 공유합니다.
1. 문제 현상: 방금 올린 이미지가 왜 1시간 뒤에 깨질까?
- 초기 상태: 노션에 이미지를 직접 첨부(파일 업로드)하고 사이트를 빌드하면 데스크톱과 모바일 화면 모두에서 이미지가 선명하게 잘 나옵니다.
- 1시간 경과 후: 페이지 새로고침 시 이미지가 로드되지 않고
403 Forbidden또는AccessDenied에러와 함께 깨진 이미지 아이콘이 출력됩니다.
개발자 도구(Network 탭)를 열어 이미지 URL을 확인해 보면 원인은 즉시 드러납니다. 이미지 주소가 다음과 같은 형태로 구성되어 있습니다.
[https://prod-files-secure.s3.us-west-2.amazonaws.com/.../image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=20260930T...&X-Amz-Expires=3600&X-Amz-Signature=](https://prod-files-secure.s3.us-west-2.amazonaws.com/.../image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=20260930T...&X-Amz-Expires=3600&X-Amz-Signature=)...
주소 파라미터 중 X-Amz-Expires=3600에 주목해야 합니다. 3600초, 즉 정확히 1시간짜리 시한부 URL입니다.
2. 근본적인 원인 분석
1) 노션의 보안 정책과 AWS S3 Presigned URL
노션에 사용자가 직접 첨부한 이미지와 파일은 노션이 관리하는 프라이빗 AWS S3 버킷에 저장됩니다. 보안상 외부에 버킷을 전체 공개(Public Read)할 수 없기 때문에, Notion API는 인증된 요청자에게만 "1시간 동안만 임시로 열람할 수 있는 서명된 주소(Presigned URL)"를 발급합니다.
2) SSG(정적 사이트 생성) 렌더링과의 충돌
- SSR(서버 사이드 렌더링) 방식이라면 방문자가 페이지를 새로고침할 때마다 매번 노션 API를 새로 호출해 최신 서명 URL을 받아오므로 문제가 겉으로 드러나지 않을 수 있습니다.
- 반면 Astro의 기본 동작인 SSG(정적 빌드)는 빌드 시점에 받아온 임시 URL을 정적 HTML 파일(
.html)에 그대로 '하드코딩(구워 넣기)'합니다. - 결국 빌드된 지 1시간이 지나면 HTML에 적힌 AWS S3 토큰이 만료되어 브라우저가 이미지를 영구적으로 불러올 수 없게 되는 것입니다.
3. 해결책: 빌드 타임 이미지 로컬 자산화 파이프라인
외부 이미지 호스팅(Cloudinary, Imgur 등)에 매번 수동으로 올리는 것은 에디터의 작성 경험을 해치는 반쪽짜리 해결책입니다. 노션의 에디터 환경을 그대로 살리려면, Astro가 빌드할 때 노션의 임시 이미지를 서버에서 다운로드하여 영구적인 정적 파일로 변환해야 합니다.
[노션 API 데이터 패칭]
│ (1시간 시한부 S3 URL 수신)
▼
[Astro 빌드 파이프라인 (Image Downloader 유틸)]
│ 1. Cover Image 및 본문 내 S3 URL 정규식 추출
│ 2. fetch로 원본 이미지 바이너리 다운로드
│ 3. public/images/notion/[slug]/ 폴더에 로컬 파일로 저장
│ 4. 본문 HTML 내 이미지 경로를 로컬 주소(/images/notion/...)로 치환
▼
[Cloudflare Pages 배포 아티팩트] 영구 보존되는 정적 자산으로 배포 완료
4. 실무 구현 가이드
1) 이미지 다운로더 유틸 작성 (src/lib/notionImageDownloader.ts)
Astro 빌드 시점에 Node.js의 fs 모듈과 fetch를 활용해 원본 이미지를 다운로드하고 경로를 치환하는 함수를 구현합니다. 중복 다운로드를 막기 위한 파일 존재 여부 체크도 포함합니다.
import fs from "node:fs";
import path from "node:path";
export async function downloadAndReplaceNotionImages(contentMarkdown: string, slug: string): Promise<string>{
const targetDir = path.join(process.cwd(), "public", "images", "notion", slug);
if (!fs.existsSync(targetDir)) {
fs.mkdirSync(targetDir, { recursive: true });
}
// 노션 S3 임시 URL 정규식 패턴 탐색
const s3UrlRegex = /https:\/\/prod-files-secure\.s3[^\s)"']+/g;
const matches = [...new Set(contentMarkdown.match(s3UrlRegex) || [])];
let updatedMarkdown = contentMarkdown;
for (let i = 0; i < matches.length; i++) {
const s3Url = matches[i];
// 확장자 추출 (.png, .jpg 등 기본 png 처리)
const urlObj = new URL(s3Url);
const ext = path.extname(urlObj.pathname) || ".png";
const fileName = `image-${i + 1}${ext}`;
const filePath = path.join(targetDir, fileName);
const localPublicUrl = `/images/notion/${slug}/${fileName}`;
try {
// 이미 다운로드된 파일이 없다면 다운로드 실행
if (!fs.existsSync(filePath)) {
const response = await fetch(s3Url);
if (response.ok) {
const arrayBuffer = await response.arrayBuffer();
fs.writeFileSync(filePath, Buffer.from(arrayBuffer));
}
}
// 마크다운 내부의 임시 URL을 영구적인 로컬 정적 주소로 치환
updatedMarkdown = updatedMarkdown.replaceAll(s3Url, localPublicUrl);
} catch (error) {
console.error(`이미지 다운로드 실패 (${s3Url}):`, error);
}
}
return updatedMarkdown;
}
2) 커버 이미지(Cover Image) 처리
포스트 상단에 노출되는 대표 썸네일 역시 노션 첨부 파일(type === 'file')일 경우 동일한 방식으로 다운로드하여 영구 경로로 바인딩합니다.
// src/lib/notion.ts 내부 발췌
let coverImageUrl = "";
if (post.coverImage?.type === "file") {
const originalUrl = post.coverImage.file.url;
const ext = path.extname(new URL(originalUrl).pathname) || ".jpg";
const fileName = `cover${ext}`;
const saveDir = path.join(process.cwd(), "public", "images", "notion", slug);
if (!fs.existsSync(saveDir)) {
fs.mkdirSync(saveDir, { recursive: true });
}
const filePath = path.join(saveDir, fileName);
if (!fs.existsSync(filePath)) {
const res = await fetch(originalUrl);
if (res.ok) {
fs.writeFileSync(filePath, Buffer.from(await res.arrayBuffer()));
}
}
coverImageUrl = `/images/notion/${slug}/${fileName}`;
}
5. 결론 및 도입 효과
이 다운로드 파이프라인을 도입한 뒤 얻은 핵심 성과는 다음과 같습니다:
- 영구적인 안정성: 배포 후 몇 주, 몇 달이 지나도 이미지가 만료되지 않고 Cloudflare 엣지 CDN에서 초고속으로 서빙됩니다.
- 에디터 경험 극대화: 작성자는 외부 이미지 업로더를 거칠 필요 없이, 노션 편집기 화면에 이미지를 편하게 복사-붙여넣기(
Ctrl + V)하기만 하면 됩니다. - 완벽한 데이터 자산화: 노션 서비스에 장애가 생기거나 API 정책이 바뀌더라도, 이미 빌드된 정적 이미지 자산은 내 프로젝트의 소유(
public/images/...)로 안전하게 보존됩니다.
노션을 Headless CMS로 연동하여 정적 사이트를 빌드할 계획이라면, 첫날 반드시 이 이미지 다운로드 파이프라인을 가장 먼저 구축해 두는 것을 권장합니다.
2026-09-30 업데이트: 실무 배포 검증 및 영구 자산화 완료
노션 S3 Presigned URL의 1시간(X-Amz-Expires=3600) 만료 이슈를 확인한 후, 빌드 타임 로컬 자산화 파이프라인을 최종 배포하여 정상 동작을 검증했습니다.
1. 적용된 빌드 타임 파이프라인 구조
외부 유료 이미지 호스팅(Cloudinary 등)을 별도로 연결하지 않고, Astro의 정적 빌드 라이프사이클을 활용해 로컬 정적 에셋으로 영구 전환했습니다.
[노션 API 호출] (1시간짜리 임시 S3 URL 반환)
│
▼
[빌드 타임 이미지 다운로더 (Astro Build)]
│ 1. 대표 이미지(Cover) 및 본문 마크다운 이미지 URL 감지
│ 2. public/notion-images/{slug}/ 경로로 원본 바이너리 다운로드
│ 3. HTML 내 이미지 src를 /notion-images/{slug}/... 로 영구 경로 치환
▼
[Cloudflare Pages 정적 자산 배포]
│ - 이미지 파일이 dist 빌드 결과물에 포함되어 엣지 CDN에 업로드
▼
[최종 결과] 노션 만료 시간과 무관하게 사이트 도메인 기반 영구 서빙
2. 핵심 최적화 및 안정성 보장 포인트
- 불필요한 중복 다운로드 방지 (해시/파일명 기반 캐싱): 로컬 개발 환경(
npm run dev)이나 반복 빌드 시 이미 내려받은 이미지가 존재하면 다운로드를 건너뛰어 빌드 속도 저하를 방지했습니다. - 마크다운 본문 내 다중 이미지 일괄 치환: 대표 썸네일뿐 아니라 본문에 삽입된 인라인 이미지, 시맨틱
<figure>내부의 이미지 주소까지 정규식으로 추적하여 로컬 경로로 일괄 자동 매핑했습니다. - 도메인 독립성 확보: 외부 AWS S3 주소 종속성을 제거하고 자체 도메인 에셋(
https://mktg.kr/notion-images/...)으로 서빙되도록 구성하여 서드파티 차단 위험을 해소하고 이미지 로딩 레이턴시를 대폭 단축했습니다.
💡 1시간 만료 시점 이후에도 대표 이미지와 본문 콘텐츠 이미지가 깨짐 없이 영구적으로 안정 서빙되는 것을 최종 확인했습니다.
KEEP READING
왜 2026년 마케터와 개발자는 정적 헤드리스 CMS로 이동하는가?
2026년 기업 웹 환경이 워드프레스·줌라·드루팔 같은 모놀리식 CMS에서 정적 헤드리스 아키텍처로 전환하는 핵심 이유는 모바일 코어 웹 바이탈 격차(정적 Astro 84% vs 워드프레스 45%), 연간 1만 건이 넘는 서드파티 플러그인 보안 취약점, 그리고 AI 에이전트 크롤링 효율성(GEO) 때문입니다. 정적 헤드리스 전환 시 LCP는 최대 76% 단축되며, AI 답변 엔진을 통해 유입된 방문자는 전통 검색 대비 최대 9배 높은 전환율을 기록합니다.
웹사이트 리다이렉트 완전 정복 301, 302, 307, 308 차이점과 올바른 선택법
웹사이트를 운영하다 보면 도메인을 변경하거나 페이지 구조를 개편하면서 기존 URL을 새로운 URL로 연결해야 하는 상황이 발생합니다. 이때 올바른 HTTP 리다이렉트(Redirect) 코드를 선택하는 것은 사용자 경험(UX)뿐만 아니라 검색엔진 최적화(SEO) 관점에서도 매우 중요합니다. 이번 영상에서 301, 302, 307, 308 리다이렉트의 정확한 차이점과 언제 어떤 코드를 써야 하는지 알아보겠습니다.
404 에러 페이지, 방치해도 괜찮을까? 구글이 밝힌 오해와 3단계 관리 프레임워크
구글 서치 콘솔의 404 에러는 도메인 페널티나 크롤링 예산 고갈을 유발하지 않습니다. Google Search Central이 밝힌 HTTP 상태 코드별 신호 차이, 홈페이지 일괄 리다이렉트 시 발생하는 소프트 404(Soft 404) 해결법, 그리고 3단계 URL 관리 프레임워크를 정리했습니다.