Nuxt 4 패턴
SSR, 하이브리드 렌더링, 라우트 규칙 또는 페이지 수준 데이터 페칭을 사용하는 Nuxt 4 앱을 빌드하거나 디버깅할 때 사용합니다.
활성화 시점
- 서버 HTML과 클라이언트 상태 간의 수화 불일치(Hydration Mismatch)
- prerender, SWR, ISR 또는 클라이언트 전용 섹션과 같은 라우트 수준 렌더링 결정
- 지연 로딩, 지연 수화 또는 페이로드 크기 관련 성능 작업
useFetch,useAsyncData또는$fetch를 사용한 페이지 또는 컴포넌트 데이터 페칭- 라우트 파라미터, 미들웨어 또는 SSR/클라이언트 차이와 관련된 Nuxt 라우팅 문제
수화 안전성
- 첫 번째 렌더는 결정적(Deterministic)이어야 합니다.
Date.now(),Math.random(), 브라우저 전용 API 또는 storage 읽기를 SSR 렌더링된 템플릿 상태에 직접 넣지 마십시오. - 서버가 동일한 마크업을 생성할 수 없는 경우 브라우저 전용 로직을
onMounted(),import.meta.client,ClientOnly또는.client.vue컴포넌트 뒤로 이동하십시오. - Nuxt의
useRoute()컴포저블(Composable)을 사용하고,vue-router의 것은 사용하지 마십시오. - SSR 렌더링된 마크업을 구동하기 위해
route.fullPath를 사용하지 마십시오. URL 프래그먼트는 클라이언트 전용이므로 수화 불일치를 일으킬 수 있습니다. ssr: false는 진정한 브라우저 전용 영역을 위한 탈출구로 취급하고, 불일치에 대한 기본 수정으로 사용하지 마십시오.
데이터 페칭
- 페이지와 컴포넌트에서 SSR-안전 API 읽기를 위해
await useFetch()를 선호하십시오. 서버에서 가져온 데이터를 Nuxt 페이로드에 전달하고 수화 시 두 번째 페치를 방지합니다. - 페처(Fetcher)가 단순한
$fetch()호출이 아닌 경우, 사용자 정의 키가 필요한 경우, 또는 여러 비동기 소스를 구성해야 하는 경우useAsyncData()를 사용하십시오. - 캐시 재사용과 예측 가능한 새로고침 동작을 위해
useAsyncData()에 안정적인 키를 제공하십시오. useAsyncData()핸들러를 부수 효과(Side-effect) 없이 유지하십시오. SSR 및 수화 중에 실행될 수 있습니다.$fetch()는 사용자 트리거 쓰기 또는 클라이언트 전용 작업에 사용하고, SSR에서 수화되어야 하는 최상위 페이지 데이터에는 사용하지 마십시오.- 탐색을 차단해서는 안 되는 중요하지 않은 데이터에 대해
lazy: true,useLazyFetch()또는useLazyAsyncData()를 사용하십시오. UI에서status === 'pending'을 처리하십시오. - SEO 또는 첫 페인트에 필요하지 않은 데이터에만
server: false를 사용하십시오. pick으로 페이로드 크기를 줄이고, 깊은 반응성이 필요하지 않은 경우 더 얕은 페이로드를 선호하십시오.
const route = useRoute()
const { data: article, status, error, refresh } = await useAsyncData(
() => `article:${route.params.slug}`,
() => $fetch(`/api/articles/${route.params.slug}`),
)
const { data: comments } = await useFetch(`/api/articles/${route.params.slug}/comments`, {
lazy: true,
server: false,
})
라우트 규칙
렌더링 및 캐싱 전략을 위해 nuxt.config.ts에서 routeRules를 선호하십시오:
export default defineNuxtConfig({
routeRules: {
'/': { prerender: true },
'/products/**': { swr: 3600 },
'/blog/**': { isr: true },
'/admin/**': { ssr: false },
'/api/**': { cache: { maxAge: 60 * 60 } },
},
})
prerender: 빌드 시 정적 HTMLswr: 캐시된 콘텐츠를 제공하고 백그라운드에서 재검증isr: 지원되는 플랫폼에서 증분 정적 재생성ssr: false: 클라이언트 렌더링된 라우트cache또는redirect: Nitro 수준 응답 동작
라우트 규칙을 전역이 아닌 라우트 그룹별로 선택하십시오. 마케팅 페이지, 카탈로그, 대시보드 및 API는 일반적으로 다른 전략이 필요합니다.
지연 로딩 및 성능
- Nuxt는 이미 라우트별로 페이지를 코드 분할합니다. 미세 최적화 컴포넌트 분할 전에 라우트 경계가 의미 있는지 확인하십시오.
Lazy접두사를 사용하여 중요하지 않은 컴포넌트를 동적으로 가져오십시오.v-if로 지연 컴포넌트를 조건부로 렌더링하여 UI가 실제로 필요할 때까지 청크가 로드되지 않도록 하십시오.- 스크롤 없이 보이지 않는 부분이나 중요하지 않은 대화형 UI에는 지연 수화를 사용하십시오.
<template>
<LazyRecommendations v-if="showRecommendations" />
<LazyProductGallery hydrate-on-visible />
</template>
- 사용자 정의 전략의 경우 가시성 또는 유휴 전략과 함께
defineLazyHydrationComponent()를 사용하십시오. - Nuxt 지연 수화는 단일 파일 컴포넌트에서 작동합니다. 지연 수화된 컴포넌트에 새 props를 전달하면 즉시 수화가 트리거됩니다.
- 내부 탐색을 위해
NuxtLink를 사용하여 Nuxt가 라우트 컴포넌트와 생성된 페이로드를 프리페치할 수 있도록 하십시오.
리뷰 체크리스트
- 첫 번째 SSR 렌더와 수화된 클라이언트 렌더가 동일한 마크업을 생성합니다.
- 페이지 데이터는 최상위
$fetch가 아닌useFetch또는useAsyncData를 사용합니다. - 중요하지 않은 데이터는 지연되고 명시적인 로딩 UI가 있습니다.
- 라우트 규칙이 페이지의 SEO 및 신선도 요구 사항과 일치합니다.
- 무거운 대화형 아일랜드는 지연 로딩되거나 지연 수화됩니다.