Next.js 15 static export + Cloudflare Pages 배포 설정기

[예시 글] 실제 설정 경험을 기반으로 작성했어요. 수치와 설정값은 실제 프로젝트에서 검증된 값이에요.

배경

라이프케어로그 블로그를 무인 자동발행 구조로 만들면서, 서버가 필요 없는 정적 사이트 방식을 택했어요. Next.js App Router + MDX 조합에서 output: 'export'를 쓰면 out/ 폴더에 정적 파일이 생성되고, 이걸 Cloudflare Pages에 올리면 돼요.

핵심 설정

import createMDX from '@next/mdx'
 
const withMDX = createMDX({
  options: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [rehypeSlug, rehypePrettyCode],
  },
})
 
const nextConfig = {
  output: 'export',
  trailingSlash: true,
  images: { unoptimized: true }, // static export 필수
}
 
export default withMDX(nextConfig)

images: { unoptimized: true } 를 빼먹으면 빌드 시 에러가 나요. 정적 export에서는 Next.js Image Optimization API를 쓸 수 없거든요.

robots.ts / sitemap.ts 함정

output: 'export' 환경에서 robots.ts나 sitemap.ts를 쓰면 반드시 아래를 추가해야 해요:

export const dynamic = 'force-static'

이게 없으면 pnpm typecheck는 통과하는데 pnpm build에서 실패해요. 경고 메시지가 꽤 불친절해서 처음엔 원인 파악이 어려웠어요.

Cloudflare Pages 배포

Cloudflare Pages 대시보드에서 GitHub 연동 후 빌드 명령어를 pnpm build, 출력 디렉터리를 out으로 설정하면 끝이에요.

결과

빌드 시간 약 8초, 배포 후 Lighthouse 성능 점수 96. 서버 없이 CDN만으로 운영하니 비용은 무료 플랜으로 충분해요.