Nuxt 4 패턴
SSR, 하이브리드 렌더링, 라우트 규칙 또는 페이지 수준 데이터 가져오기를 사용하는 Nuxt 4 앱을 빌드하거나 디버깅할 때 사용하세요.
활성화 시점
- 서버 HTML과 클라이언트 상태 간의 하이드레이션 불일치
- prerender, SWR, ISR 또는 클라이언트 전용 섹션과 같은 라우트 수준 렌더링 결정
- 지연 로딩, 지연 하이드레이션 또는 페이로드 크기와 관련된 성능 작업
useFetch,useAsyncData또는$fetch를 사용한 페이지 또는 컴포넌트 데이터 가져오기- 라우트 파라미터, 미들웨어 또는 SSR/클라이언트 차이로 인한 Nuxt 라우팅 문제
하이드레이션 안전성
- 첫 번째 렌더링을 결정론적으로 유지하세요.
Date.now(),Math.random(), 브라우저 전용 API 또는 저장소 읽기를 SSR 렌더링 템플릿 상태에 직접 넣지 마세요. - 서버가 동일한 마크업을 생성할 수 없는 경우 브라우저 전용 로직을
onMounted(),import.meta.client,ClientOnly또는.client.vue컴포넌트 뒤로 이동하세요. vue-router의 것이 아닌 Nuxt의useRoute()컴포저블을 사용하세요.- SSR 렌더링 마크업을 구동하기 위해
route.fullPath를 사용하지 마세요. URL 프래그먼트는 클라이언트 전용이므로 하이드레이션 불일치를 만들 수 있습니다. ssr: false를 불일치에 대한 기본 수정 사항이 아닌, 진정한 브라우저 전용 영역을 위한 탈출구로 취급하세요.
데이터 가져오기
- 페이지 및 컴포넌트에서 SSR 안전 API 읽기를 위해
await useFetch()를 선호하세요. 서버에서 가져온 데이터를 Nuxt 페이로드로 전달하고 하이드레이션 시 두 번째 가져오기를 방지합니다. - fetcher가 단순한
$fetch()호출이 아닌 경우, 사용자 정의 키가 필요한 경우, 또는 여러 비동기 소스를 구성하는 경우useAsyncData()를 사용하세요. - 캐시 재사용 및 예측 가능한 새로 고침 동작을 위해
useAsyncData()에 안정적인 키를 제공하세요. useAsyncData()핸들러를 부작용이 없도록 유지하세요. 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프리픽스를 사용하여 중요하지 않은 구성 요소를 동적으로 가져오세요.- UI에서 실제로 필요할 때까지 청크가 로드되지 않도록
v-if와 함께 지연 구성 요소를 조건부로 렌더링하세요. - 접히는 영역 아래 또는 중요하지 않은 대화형 UI에 대해 지연 하이드레이션을 사용하세요.
<template>
<LazyRecommendations v-if="showRecommendations" />
<LazyProductGallery hydrate-on-visible />
</template>
- 사용자 정의 전략의 경우 가시성 또는 유휴 전략과 함께
defineLazyHydrationComponent()를 사용하세요. - Nuxt 지연 하이드레이션은 단일 파일 구성 요소에서 작동합니다. 지연 하이드레이션된 구성 요소에 새 prop을 전달하면 즉시 하이드레이션이 트리거됩니다.
- 내부 탐색에는
NuxtLink를 사용하여 Nuxt가 라우트 구성 요소 및 생성된 페이로드를 미리 가져올 수 있도록 하세요.
검토 체크리스트
- 첫 번째 SSR 렌더링과 하이드레이션된 클라이언트 렌더링이 동일한 마크업을 생성합니다.
- 페이지 데이터는 최상위
$fetch가 아닌useFetch또는useAsyncData를 사용합니다. - 중요하지 않은 데이터는 지연되고 명시적인 로딩 UI가 있습니다.
- 라우트 규칙이 페이지의 SEO 및 최신성 요구 사항과 일치합니다.
- 무거운 대화형 섹션은 지연 로드되거나 지연 하이드레이션됩니다.