Next.js App Router 프로덕션 배포 전 점검 체크리스트 45항목. 라우팅·레이아웃, fetch 캐싱·revalidate, 렌더링 모드, 보안 헤더·미들웨어, SEO 메타·구조화 데이터, next/image·폰트, 에러 관측, Core Web Vitals·배포 게이트까지 프론트엔드 실무 기준으로 정리한다. React 서버 컴포넌트 환경에서 출시 직전 놓치기 쉬운 항목을 팀 온보딩·릴리즈 문서에 바로 쓸 수 있게 구성했다.
Next.js App Router로 만든 서비스를 프로덕션에 올리기 직전에 "뭐가 빠졌지?" 하고 막막해진 적이 있습니다. 로컬에서는 잘 뜨는데 캐시가 꼬이거나, 메타 태그가 비어 있거나, 보안 헤더가 하나도 없는 채로 배포되는 경우가 생각보다 많습니다.
이 글은 App Router 기준으로 프로덕션 출시 전에 점검하는 45개 항목 체크리스트입니다. 라우팅·데이터 페칭·캐싱, 렌더링 모드, 보안 헤더·미들웨어, SEO 메타·구조화 데이터, 이미지·폰트, 에러 처리, 성능까지 단계별로 나눴습니다. 배포 직전 30분 점검용으로 쓰거나, 팀 온보딩 문서에 그대로 붙여 넣어도 됩니다.
App Router의 핵심은 폴더 기반 라우트와 레이아웃 중첩입니다. app/ 아래에 page.js, layout.js, loading.js, error.js, not-found.js가 제자리에 있는지부터 확인합니다. 레이아웃이 너무 무거우면 하위 페이지 전체가 느려지고, loading.js가 없으면 느린 서버 컴포넌트에서 빈 화면이 길게 유지됩니다.
동적 세그먼트([slug])와 캐치올([...slug]) 사용 시 generateStaticParams 유무, dynamicParams 설정, 404 처리 경로를 반드시 명시합니다. 특히 정적 사이트 생성(SSG)으로 가는 페이지와 요청마다 렌더하는 페이지를 한 트리에 섞을 때는 부모 레이아웃의 동적 옵션이 자식까지 오염되지 않는지 점검해야 합니다.
App Router에서 fetch는 기본적으로 캐시 정책을 따릅니다. 버전과 설정에 따라 기본값이 달라지므로, "기본값에 맡긴다"는 선택이 가장 위험합니다. 페이지마다 cache, next.revalidate, tags를 명시하고, 사용자별 데이터가 섞이지 않도록 요청 메모이제이션 범위를 이해해야 합니다.
서버 액션·라우트 핸들러에서 쓰는 데이터와 페이지 렌더용 데이터는 수명이 다릅니다. 목록 페이지는 짧은 재검증, 약관·고정 콘텐츠는 긴 재검증, 대시보드는 no-store에 가깝게 두는 식으로 구분합니다. 캐시 무효화는 revalidatePath / revalidateTag를 배포·어드민 액션에 연결해 두어야 운영이 가능합니다.
App Router는 한 페이지 안에서도 정적 셸과 동적 조각을 섞을 수 있습니다. 문제는 "이 페이지가 빌드 타임에 굳는지, 요청마다 도는지"를 팀이 공유하지 않을 때입니다. 빌드 로그에서 정적(●)·동적(λ/ƒ) 표기를 확인하고, 의도치 않은 동적 강제 요소(cookies(), headers(), 검색 파라미터)를 찾아냅니다.
스트리밍과 Suspense 경계는 체감 속도를 올리지만, 핵심 콘텐츠가 늦게 오면 SEO·광고 뷰어빌리티에 영향을 줍니다. 위쪽 접히는 영역(above the fold)은 가능한 한 빠르게 완성하고, 아래쪽 추천·댓글·위젯을 스트리밍으로 미루는 편이 안전합니다. 프리렌더가 필요한 마케팅 페이지와 로그인 영역은 라우트 그룹으로 분리하는 것이 관리하기 쉽습니다.
Next.js 기본 설정만으로는 보안 헤더가 충분하지 않습니다. Content-Security-Policy, X-Frame-Options 또는 frame-ancestors, Referrer-Policy, Permissions-Policy를 next.config의 headers() 또는 엣지 미들웨어에서 넣어야 합니다. 특히 관리자·결제·로그인 경로는 미들웨어에서 인증 상태를 먼저 거르고, 페이지 내부 검사만 믿지 않습니다.
서버 액션은 공개 HTTP 엔드포인트와 비슷하게 취급해야 합니다. 입력 검증(Zod 등), CSRF 대응 전략, Rate limit, 권한 체크를 액션 본문 앞에 둡니다. 환경 변수는 NEXT_PUBLIC_ 접두사가 붙은 것만 브라우저에 노출된다는 규칙을 팀 전체가 알고 있어야 하며, API 키·DB URL·서비스 롤 키는 서버 전용으로 유지합니다.
App Router의 generateMetadata / metadata API는 페이지별 제목·설명·오픈그래프·캐노니컬을 한곳에서 관리할 수 있게 해 줍니다. 문제는 기본 레이아웃 메타만 두고 상세 페이지 메타를 비워 두거나, OG 이미지가 깨진 채로 공유되는 경우입니다. 검색엔진과 SNS 카드 미리보기를 배포 전에 실제 URL로 확인하는 습관이 필요합니다.
구조화 데이터(JSON-LD)는 Article, FAQPage, BreadcrumbList 등 페이지 유형에 맞게 넣되, 본문에 없는 별점·리뷰를 만들어 넣지 않습니다. 사이트맵·robots·RSS/Atom이 있으면 크롤 경로가 명확해지고, noindex가 필요한 검색·어드민·프리뷰 페이지는 반드시 제외합니다.
next/image는 리사이즈·포맷 변환·지연 로딩을 자동화하지만, 원격 도메인 허용 목록·크기 지정·우선순위 설정이 빠지면 CLS(레이아웃 이동)나 느린 LCP가 납니다. 히어로 이미지는 priority를 주고, 목록 썸네일은 적절한 sizes를 넣습니다. SVG·아이콘은 불필요하게 이미지 최적화 파이프라인을 타지 않게 구분합니다.
폰트는 next/font로 셀프 호스팅하면 외부 폰트 CSS 왕복을 줄일 수 있습니다. 가변 폰트 가중치를 필요한 것만 넣고, display: swap 또는 프레임워크 기본 전략으로 FOIT를 피합니다. public 폴더의 파비콘·매니페스트·OG 기본 이미지도 루트에서 직접 200 응답이 나는지 확인합니다.
프로덕션에서 가장 위험한 상태는 "사용자가 흰 화면을 보는데 알림이 없는 상태"입니다. 라우트 단위 error.js, 전역 에러 경계, 404 페이지 문구, 서버 로그 상관 ID를 맞춰 둡니다. 클라이언트 에러는 Sentry 같은 도구로, 서버 로그는 구조화 JSON으로 모아 요청 ID로 추적할 수 있어야 합니다.
헬스체크 URL, 업타임 모니터, 핵심 전환 퍼널(가입·결제·글 작성)에 대한 합성 모니터링을 최소 하나라도 두는 것을 권합니다. 개인정보가 로그에 찍히지 않도록 마스킹 규칙을 정하고, 에러 메시지에 스택·내부 경로가 사용자에게 노출되지 않게 합니다.
출시 직전에는 기능보다 회귀를 막는 확인이 우선입니다. 프로덕션 빌드(next build)로 번들 분석, 미사용 의존성, 과도한 클라이언트 컴포넌트를 점검합니다. 환경 변수는 스테이징과 프로덕션 키가 분리돼 있는지, 미리보기 배포에 운영 DB가 연결되지 않았는지 확인합니다.
Core Web Vitals는 Lighthouse 한 번으로 끝내지 말고, 실제 필드 데이터(CrUX 또는 분석 도구의 INP/LCP)를 볼 계획을 잡습니다. 배포 플랫폼(버셀 등)의 리전, 함수 타임아웃, 이미지 최적화 한도, 트래픽 급증 시 스케일 설정도 체크리스트에 넣어둡니다. 출시 후 첫 1시간은 에러율·응답 시간 대시보드를 열어 두는 것이 좋습니다.
45개 항목을 매 배포마다 전부 손으로 체크하면 금방 피로해집니다. 1인 개발자는 "보안 헤더·메타·에러 트래킹·환경 변수 분리" 네 가지만 고정 게이트로 두고, 나머지는 월 1회 감사로 돌리는 방식이 현실적입니다. 팀이면 PR 템플릿에 해당 영역 체크박스를 넣고, 릴리즈 매니저가 배포 직전 보안·SEO·관측 세 섹션만 재확인합니다.
자동화할 수 있는 항목은 CI로 옮깁니다. 예: 린트·타입·테스트·번들 크기 임계값·Lighthouse CI·의존성 감사. 자동화되지 않는 항목(카피 품질, 비즈니스 권한 모델, 롤백 커뮤니케이션)만 사람이 봅니다. 체크리스트는 살아 있는 문서여야 하므로, 사고 회고 때마다 빠진 항목을 한 줄 추가하는 규칙을 권합니다.
대부분 항목은 그대로 적용됩니다. 다만 generateMetadata, loading.js/error.js, 서버 액션, App Router 전용 캐시 API는 Pages Router에 없거나 형태가 다릅니다. Pages Router라면 _app/_document, getStaticProps/getServerSideProps, 커스텀 에러 페이지 기준으로 같은 질문을 바꿔 적용하면 됩니다.
1인·소규모라면 다음 여섯 가지를 최소 게이트로 둡니다. ① 프로덕션 빌드·타입·린트 통과 ② 환경 변수 분리 ③ 보안 헤더와 인증 미들웨어 ④ 메타·OG·캐노니컬 ⑤ 에러 트래킹 연동 ⑥ 배포 후 스모크 테스트. 나머지는 월 1회 감사로 보완해도 큰 사고 확률을 크게 낮출 수 있습니다.
버전 기본값에 의존하지 말고 요청마다 cache 또는 next.revalidate를 명시하는 것이 가장 안전합니다. 공식 문서의 현재 기본값을 확인한 뒤, 팀 컨벤션으로 "명시 없는 fetch 금지"를 린트 규칙이나 코드 리뷰 기준으로 고정하세요. 캐시 버그는 재현이 어려워 초기에 규칙을 세우는 편이 비용이 낮습니다.
생략하면 안 됩니다. 미들웨어는 1차 방어선이고, 서버 컴포넌트·서버 액션·라우트 핸들러에서 리소스 단위 권한을 다시 확인해야 합니다. 미들웨어 우회, 캐시된 응답, 직접 API 호출 경로가 항상 존재할 수 있기 때문입니다. "앞단에서 막았으니 뒤는 안전하다"는 가정이 권한 사고의 흔한 원인입니다.
정적 내보내기는 서버 기능(미들웨어 일부, 서버 액션, 요청 시 렌더, 이미지 최적화 기본 동작 등)이 제한됩니다. SEO·보안 헤더(호스팅 단 설정)·이미지·성능 항목은 유효하지만, 동적 캐시·서버 권한 모델은 호스팅/외부 API 설계로 대체해야 합니다. 정적 사이트라면 체크리스트에서 서버 전용 항목을 제외한 축소판을 만드세요.
유효합니다. 오히려 자체 호스팅은 헤더·HTTPS·프로세스 매니저·로그 수집을 직접 구성해야 하므로 보안·관측·배포 섹션 비중이 더 커집니다. 공식 프로덕션 체크리스트의 호스팅 관련 항목과 함께, 리버스 프록시 타임아웃, 헬스체크, 제로 다운타임 배포 전략을 추가하는 것을 권합니다.
