Nuxt 서버 경계와 Vite 배포 검증 | Nuxt Server Boundaries and Vite Deployment Checks

핵심 답변: 최근 72시간 Nuxt 생태계의 핵심은 ‘새 기능 나열’보다 서버 경계·개발 서버·번들 출력의 운영 계약을 함께 점검하라는 신호입니다. Nuxt 4.6은 nuxt/server로 서버 API의 이식성을 강화했고, H3 2.0.2와 Vite 8.3.4는 각각 오류 처리·빌드/HMR 안정성을 보완했습니다.

요약: Nuxt/Vue 프론트엔드 팀은 이번 3일 동안 공개된 Nuxt 4.6, Nuxt CLI v4, H3 2.0.2, Vite 8.3.4를 한 묶음으로 검토해야 합니다. 즉시 전면 전환할 필요는 없지만 Node 런타임, server handler import, HMR·비루트 배포의 preload, CI 로그 형식을 작은 검증 브랜치에서 확인하는 것이 안전합니다.

3일 결론

확인된 사실: Nuxt 4.6(10월 6일 KST)은 서버 코드를 Nitro/H3의 직접 import에서 분리할 수 있는 nuxt/server와 CLI v4를 함께 제공합니다. H3 2.0.2(10월 7일 KST)는 Node stream 오류·redirect/no-content 응답·오류 미들웨어 처리를 고쳤고, Vite 8.3.4(10월 8일 KST)는 chunk import map의 non-root base preload와 HMR/restart·watcher 문제를 보완했습니다.

실무 판단: 이는 ‘모든 앱을 새 런타임으로 옮기라’는 공지가 아닙니다. 새 API와 공용 모듈은 nuxt/server을 기본 경계로 삼고, Vite를 직접 또는 Nuxt를 통해 쓰는 앱은 preview 배포에서 base path·CSS preload·HMR을 재현하는 편이 비용 대비 효과가 큽니다. Nitro의 Vitest 통합 커밋은 아직 main 브랜치의 미출시 작업이므로 운영 의존성으로 채택하지 않습니다.

이번 72시간에 선별한 6개 이슈

Nuxt 4.6.0 정식: 서버-agnostic 방향, nuxt/server, portable request event 및 typed $fetch 표면을 공개했습니다.
Nuxt CLI 4.0.0 정식: dev TUI, 요청 단위 로그/오류 관찰, lock file 및 nuxt curl/nuxt task를 추가했습니다.
H3 2.0.2 정식: Node handler stream 오류의 onError 호출, redirect/no-content reason phrase, handled response 전달을 수정했습니다.
Vite 8.3.4 정식: non-root base + chunk import map preload, 재시작 중 재시작 요청, 정적 alias 경계, watcher 및 dependency scan을 보완했습니다.
Nuxt main 미출시: setPageLayout(false) 타입 허용 등의 후속 수정이 병합됐습니다. 다음 patch 후보일 수 있으나 아직 릴리스가 아닙니다.
Nitro main 미출시: Vite plugin을 통한 Vitest/Nitro runtime 테스트 지원이 병합됐습니다. 릴리스 노트가 나오기 전까지는 관찰 대상입니다.

흐름 1 — Nuxt 4.6의 핵심은 ‘서버 구현’이 아니라 ‘서버 경계’

사실과 근거

Nuxt 4.6은 정식 릴리스 노트에서 nuxt/server를 handler·middleware·서버 유틸리티를 위한 새 import surface로 설명합니다. 기본 구현은 여전히 Nitro이지만, API는 portable RequestEvent와 web standard 중심으로 설계됐습니다. 공식 발표는 이 경계가 Nuxt 5의 Nitro v3/H3 v2 전환을 부드럽게 하고, 실험적 @nuxt/vite-server도 가능하게 한다고 밝힙니다.

시사점

h3나 nitropack을 직접 import한 모든 파일을 일괄 치환할 이유는 없습니다. 다만 새 server/api와 재사용되는 모듈은 문서화된 Nuxt 경계를 우선하면 서버 엔진 major 변화에 덜 묶입니다. 파일 업로드 등 새 표면에 없는 기능은 기존 H3 API를 유지하고, 경계를 섞는 파일만 별도로 테스트합니다.

import { defineEventHandler, getQuery } from 'nuxt/server'

export default defineEventHandler((event) => {
  const { locale = 'ko' } = getQuery<{ locale?: string }>(event)
  return { locale }
})

바로 할 일

server/api, server/middleware, 사내 Nuxt module에서 h3/nitropack 직접 import를 목록화합니다.
읽기 전용 API 하나만 nuxt/server로 옮겨 typecheck, SSR 요청, preview smoke test를 통과시킵니다.
Nuxt 4.6/CLI v4는 Node.js 22.21+·24.11+·26+ 요구사항과 CI 이미지가 맞는지 먼저 확인합니다.

흐름 2 — CLI v4와 Vite 8.3.4: ‘개발 서버 문제’도 배포 전 검증 항목

Nuxt CLI v4

CLI v4 릴리스는 요청 ID, 라우트·네트워크·오류를 탐색하는 터미널 UI, source-mapped 에러 화면, 실행 중 서버와 통신하는 nuxt curl/nuxt task를 제공합니다. CI나 non-TTY에서는 일반 로그로 fallback하며 --no-tui 또는 NUXT_TUI=plain을 쓸 수 있습니다. 따라서 로그 파서가 TUI 텍스트에 의존하면 안 됩니다.

Vite 8.3.4

Vite 8.3.4는 chunkImportMap과 non-root base 조합의 preload, 진행 중 stylesheet preload, HMR 기본값 mutation, 재시작 도중의 재시작 요청, 정적 alias path boundary 등을 수정했습니다. 이는 기능 추가보다 정적 서브경로·CDN·문서 사이트·마이크로프론트엔드처럼 배포 URL이 루트가 아닌 프로젝트에 실무적으로 중요합니다.

검증 방법: base가 /app/ 같은 preview 환경에서 build→serve를 수행하고, 코드 분할 라우트의 CSS/JS preload와 새로고침을 브라우저 network 탭 및 e2e smoke test로 확인하세요. HMR은 alias import 변경, CSS 변경, 연속 재시작을 각각 재현합니다.

흐름 3 — H3 2.0.2는 서버 오류·응답 계약을 좁혀 본다

H3 2.0.2는 Node handler의 stream 오류에서 onError를 호출하고, redirect/no-content reason phrase 및 이미 처리된 응답의 오류 미들웨어 통과를 수정했습니다. 세션에서는 legacy seal fallback을 deprecated로 표시했고, route handler는 validation schema에서 입력 타입을 더 잘 추론합니다.

개발자 관점: Nuxt 4.6이 H3/Nitro 직접 결합을 줄이려는 이유가 이 변화에서 드러납니다. H3 v2를 직접 다루는 서버·모듈은 stream 실패, redirect, 빈 응답, session seal 회전의 통합 테스트를 추가하세요. Nuxt 4 앱은 의존성 강제 상향보다 Nuxt의 지원 경계를 따르는 것이 안전합니다.

미출시 관찰 — 배포 계획에 넣지 말아야 할 것

Nuxt main에는 setPageLayout(false) 타입 수정이, Nitro main에는 Vite 기반 Vitest/Nitro test environment 작업이 병합됐습니다. 둘 다 정확한 커밋으로 확인되지만 정식 릴리스가 아닙니다. 참고·실험용 브랜치 외에는 버전 pin이나 운영 일정의 근거로 사용하지 마세요.

프론트엔드 개발자 체크리스트

P0: CI/컨테이너의 Node 버전, package manager lockfile, nuxi typecheck·production build를 업그레이드 전후로 비교한다.
P0: preview의 non-root base 경로에서 lazy route, CSS/JS preload, 새로고침, redirect를 smoke test한다.
P1: 새 API·공용 Nuxt module부터 nuxt/server import를 채택하고 직접 H3 import는 인벤토리로 관리한다.
P1: H3를 직접 쓰는 서비스는 stream error·redirect·no-content·session key rotation 테스트를 만든다.
P1: CI에는 plain 로그 모드로 고정하고, 로컬에서만 CLI v4 TUI/요청 타임라인을 활용한다.
P2: Nitro의 Vitest 통합은 정식 release note가 나온 뒤 별도 spike에서 평가한다.

FAQ

Nuxt 4.6으로 올리면 모든 server handler를 바꿔야 하나요?

아닙니다. 기존 H3/Nitro import를 유지할 수 있습니다. 새 코드와 공용 모듈부터 nuxt/server을 사용하고, 파일별 테스트로 점진 전환하세요.

Vite 8.3.4는 모든 프로젝트가 긴급 적용해야 하나요?

긴급 보안 릴리스라는 근거는 없습니다. 다만 non-root base, chunk import map, HMR 재시작, alias/watch 문제가 있는 팀은 preview에서 우선 재현·검증할 가치가 있습니다.

Nitro의 Vitest 지원을 지금 도입해도 되나요?

아직 main 브랜치 커밋입니다. 출시된 패키지 기능으로 표현하거나 production 표준으로 채택하지 말고, 공식 릴리스와 문서를 기다리세요.

주요 출처

더 깊게 읽기: 실전 가이드

이 리포트는 최근 흐름을 빠르게 파악하기 위한 요약입니다. 실제 프로젝트에 적용할 때는 아래의 기준 글과 함께 확인하면 더 안전합니다.