gil
5f664546cf
- CLAUDE.md 운영 규칙 - wiki/ 정리된 지식 페이지 (Nuxt + Claude Code) - raw/ 원본 자료 - reference/ Nuxt 4.x 공식 문서 Co-authored-by: Cursor <cursoragent@cursor.com>
167 lines
4.9 KiB
Markdown
167 lines
4.9 KiB
Markdown
# Nuxt 렌더링 모드
|
|
|
|
> **카테고리:** 핵심 개념
|
|
> **최종 수정:** 2026-05-13
|
|
> **관련:** [[nuxt-lifecycle]], [[nuxt-performance]], [[nuxt-data-fetching]]
|
|
|
|
## 요약
|
|
|
|
Nuxt는 Universal(SSR), CSR, Hybrid, Edge-Side 4가지 렌더링 모드를 지원한다. 기본값은 **Universal(SSR)** 이며, `routeRules`로 라우트별로 다른 전략을 섞을 수 있다.
|
|
|
|
---
|
|
|
|
## 1. Universal Rendering (기본값, SSR + Hydration)
|
|
|
|
서버에서 완전한 HTML을 생성 → 브라우저로 전달 → 클라이언트에서 Vue가 HTML을 "인계받아" 인터랙티브하게 만듦(Hydration).
|
|
|
|
```vue
|
|
<!-- server와 client 모두에서 실행 -->
|
|
<script setup lang="ts">
|
|
const counter = ref(0) // 서버·클라이언트 양쪽에서 초기화됨
|
|
|
|
const handleClick = () => {
|
|
counter.value++ // 클라이언트에서만 실행됨
|
|
}
|
|
</script>
|
|
```
|
|
|
|
**실행 환경 요약:**
|
|
| 항목 | 서버 | 클라이언트 |
|
|
|---|---|---|
|
|
| `<script setup>` 루트 코드 | ✅ | ✅ |
|
|
| 이벤트 핸들러 | ❌ | ✅ |
|
|
| `onMounted` 훅 | ❌ | ✅ |
|
|
| Middleware / Pages | ✅ | ✅ (hydration 시) |
|
|
| `.server` 플러그인 | ✅ | ❌ |
|
|
| `.client` 플러그인 | ❌ | ✅ |
|
|
|
|
**장점:** 빠른 첫 페이지 로드, SEO 최적화, 즉각적인 콘텐츠 표시
|
|
**단점:** 서버 비용, 브라우저/서버 API 차이로 인한 개발 제약
|
|
|
|
---
|
|
|
|
## 2. Client-Side Rendering (CSR, SPA)
|
|
|
|
```typescript
|
|
// nuxt.config.ts
|
|
export default defineNuxtConfig({
|
|
ssr: false,
|
|
})
|
|
```
|
|
|
|
`ssr: false`로 설정하면 순수 SPA로 동작. 브라우저에서만 렌더링.
|
|
|
|
> 💡 경험: `ssr: false` + `nuxt generate` 조합 시 `spa-loading-template.html` 파일로 로딩 화면 제공 권장.
|
|
|
|
**장점:** 개발 편의성(브라우저 API 자유롭게 사용), 저렴한 정적 호스팅, 오프라인 지원
|
|
**단점:** 초기 로드 느림, SEO 불리
|
|
|
|
---
|
|
|
|
## 3. Hybrid Rendering (가장 실용적)
|
|
|
|
라우트별로 다른 렌더링·캐싱 전략 적용. `routeRules`로 설정.
|
|
|
|
```typescript
|
|
// nuxt.config.ts
|
|
export default defineNuxtConfig({
|
|
routeRules: {
|
|
'/': { prerender: true }, // 빌드 시 프리렌더링
|
|
'/products': { swr: true }, // 온디맨드 + 백그라운드 재검증
|
|
'/products/**': { swr: 3600 }, // TTL 1시간
|
|
'/blog': { isr: 3600 }, // CDN 캐시 1시간
|
|
'/blog/**': { isr: true }, // 다음 배포까지 CDN 캐시
|
|
'/admin/**': { ssr: false }, // 클라이언트 사이드만
|
|
'/api/**': { cors: true }, // CORS 헤더 자동 추가
|
|
'/old-page': { redirect: '/new-page' }, // 서버사이드 리다이렉트
|
|
},
|
|
})
|
|
```
|
|
|
|
### routeRules 속성 정리
|
|
|
|
| 속성 | 설명 |
|
|
|---|---|
|
|
| `prerender: true` | 빌드 시 정적 HTML 생성 |
|
|
| `swr: number \| boolean` | Stale-While-Revalidate. TTL 만료 후 백그라운드 재생성 |
|
|
| `isr: number \| boolean` | CDN에 캐시 (Netlify, Vercel 지원). `true`는 다음 배포까지 유지 |
|
|
| `ssr: false` | 해당 경로 CSR 처리 |
|
|
| `cors: true` | CORS 헤더 자동 추가 |
|
|
| `redirect: string` | 서버사이드 리다이렉트 |
|
|
| `headers: object` | 커스텀 응답 헤더 |
|
|
| `noScripts: boolean` | JS 스크립트 비활성화 |
|
|
|
|
> ⚠️ 주의: Hybrid Rendering은 `nuxt generate` 명령에서는 사용 불가. `nuxt build`만 지원.
|
|
|
|
---
|
|
|
|
## 4. Prerendering (Static Site Generation)
|
|
|
|
```bash
|
|
nuxt generate # 또는 nuxt build --prerender
|
|
```
|
|
|
|
Nitro 크롤러가 루트(`/`)부터 시작해 링크를 따라가며 모든 페이지를 HTML로 생성.
|
|
|
|
### 선택적 프리렌더링
|
|
|
|
```typescript
|
|
export default defineNuxtConfig({
|
|
nitro: {
|
|
prerender: {
|
|
routes: ['/sitemap.xml', '/user/1', '/user/2'],
|
|
ignore: ['/dynamic'],
|
|
crawlLinks: true,
|
|
},
|
|
},
|
|
})
|
|
```
|
|
|
|
페이지 레벨에서 설정 (`experimental.inlineRouteRules: true` 필요):
|
|
|
|
```vue
|
|
<script setup>
|
|
defineRouteRules({ prerender: true })
|
|
</script>
|
|
```
|
|
|
|
### Payload 시스템
|
|
|
|
프리렌더링/ISR/SWR 시 `_payload.json`이 HTML과 함께 생성됨. 클라이언트 사이드 이동 시 이 페이로드를 불러와 재요청 방지.
|
|
|
|
---
|
|
|
|
## 5. Edge-Side Rendering (ESR)
|
|
|
|
Nitro 덕분에 CDN 엣지 서버에서 직접 렌더링. 사용자와 물리적으로 가까운 곳에서 응답.
|
|
|
|
```bash
|
|
# Vercel Edge
|
|
NITRO_PRESET=vercel-edge nuxt build
|
|
|
|
# Netlify Edge Functions
|
|
NITRO_PRESET=netlify-edge nuxt build
|
|
|
|
# Cloudflare Pages
|
|
nuxt build # 자동 감지
|
|
```
|
|
|
|
---
|
|
|
|
## 배포 모드 선택 가이드
|
|
|
|
| 사이트 유형 | 권장 전략 |
|
|
|---|---|
|
|
| 블로그, 마케팅, 포트폴리오 | `prerender: true` 또는 `isr` |
|
|
| 콘텐츠 + 관리자 섹션 | Hybrid (`/admin/**` → `ssr: false`) |
|
|
| SaaS, 대시보드 | `ssr: false` (전체 CSR) |
|
|
| 전자상거래 | Hybrid (상품목록 `swr`, 상품상세 `isr`, 장바구니 `ssr`) |
|
|
|
|
---
|
|
|
|
## 참고 / 출처
|
|
|
|
- `reference/3.guide/1.concepts/1.rendering.md`
|
|
- `reference/1.getting-started/15.prerendering.md`
|
|
- `reference/1.getting-started/16.deployment.md`
|