Nuxt 4.6 nuxt/server 전환 가이드 | A Practical nuxt/server Upgrade Guide

핵심 답변: Nuxt 4.6이 2026년 10월 5일 공개됐습니다. 이번 버전의 중심은 새 기능을 많이 추가한 것보다 서버 코드를 h3와 Nitro의 구체 버전에서 한 단계 떼어 낸 nuxt/server입니다. 지금 Nuxt 4 앱을 운영한다면 모든 server/api 파일을 급히 바꿀 필요는 없습니다. 대신 새 API와 수정이 잦은 서버 모듈부터 이 경계로 옮기면 Nuxt 5·Nitro 3·H3 v2 전환 때의 충격을 줄일 수 있습니다.

실무에서 더 반가운 변화는 타입과 관찰 가능성입니다. 서버 라우트가 수백 개로 늘면서 $fetch 타입 검사에 시간이 걸리거나 TS2589 오류가 난 프로젝트, SSR 오류가 CI 로그에서만 보이던 프로젝트라면 4.6의 새 typed fetch와 CLI v4가 직접적인 점검 대상입니다. 그러나 이는 minor 릴리스라고 무심히 올릴 종류의 변화는 아닙니다. Node 버전, server handler의 import 출처, 비밀값, CI의 clean build를 한 번에 확인해야 합니다.

오늘의 결론: Nuxt 4.6의 첫 적용은 npx nuxt upgrade --dedupe가 아니라 현재 서버 경계를 눈으로 보는 일입니다. server/api에서 h3/nitropack을 직접 가져오는 파일을 목록화하고, 작은 read-only API 하나를 nuxt/server로 옮긴 뒤 typecheck·SSR·배포 smoke test를 통과시키세요. Nuxt 3은 이미 2026년 7월 31일 EOL이므로 이번 릴리스에 3.x 동반 버전은 없습니다.

무슨 일이 있었나

2026년 10월 5일, Nuxt core team: 공식 Nuxt 4.6 발표와 v4.6.0 릴리스 노트가 공개됐습니다. 4.5.2 이후 362개 이상 커밋이 포함됐고, Nuxt가 자체 request event·route rules·typed $fetch 타입을 정의하며 nuxt/server import surface를 제공합니다. 기본 서버는 여전히 Nitro이며, 순수 Vite 서버 빌드는 @nuxt/vite-server라는 실험적 선택지입니다. 공식 팀도 대부분의 앱에는 Nitro가 적합하다고 밝힙니다.

같은 날, Nuxt CLI v4: CLI v4 릴리스는 dev 서버의 터미널 UI, 요청 ID가 붙은 로그와 오류, nuxt docs, 실행 중 서버와 통신하는 nuxt curl/nuxt task, dev 서버 lock file을 소개했습니다. CI나 non-TTY에서는 일반 로그로 내려가며 --no-tui로 기존 출력을 고를 수 있습니다.

호환성 기준: 공식 발표의 업그레이드 섹션은 Node.js ^22.22.3 || ^24.15.0 || >=26.0.0을 요구합니다. 업그레이드 가이드는 Nuxt 5가 아직 개발 중이고 future.compatibilityVersion: 5로 일부 기본값을 미리 시험할 수 있다고 설명합니다. 이는 운영 전환 스위치가 아니라 호환성 테스트용 분리 브랜치에서 다룰 옵션입니다.

왜 중요한가

Nuxt 서버 코드는 그동안 편리하게 h3와 Nitro 기능을 직접 쓸 수 있었습니다. 문제는 프레임워크·서버 엔진·라우터가 각각 major 버전을 올릴 때입니다. 한 모듈의 peer dependency가 다른 앱의 H3 타입과 부딪히거나, handler가 특정 event 모양을 전제해 업그레이드를 막습니다. 4.6의 nuxt/server은 모든 기능을 감추는 추상화가 아니라, 일반적인 handler가 기대도 되는 안정적인 Nuxt 경계를 만든 것입니다.

이 변화는 보안과 운영에도 닿습니다. request·response를 web standard 중심으로 읽고, body validation과 session을 명시적으로 쓰면 handler의 입력·출력 계약이 PR에서 더 잘 보입니다. 반대로 자동 import의 H3 helper와 명시적으로 가져온 nuxt/server helper를 섞으면 event 형태가 달라 오류가 납니다. 편의상 일괄 치환하기보다 파일 단위로 테스트해야 하는 이유입니다.

1. `nuxt/server`은 다음 major를 위한 서버 경계입니다

변화: defineEventHandler, query·body·cookie·redirect·session 등 자주 쓰는 도구를 nuxt/server에서 제공하며, portable RequestEvent 타입을 씁니다. 실제 영향: 새 handler가 Nitro 2, Nitro 3, 실험적 Vite server 사이에서 같은 코드를 쓸 여지가 생깁니다. 적용 조건: 새 API나 공용 모듈부터 명시 import로 시작하세요. 예를 들어 server/api/profile.get.ts에서 다음처럼 쓸 수 있습니다.

import { defineEventHandler, getQuery } from 'nuxt/server'
export default defineEventHandler((event) => {
  const { locale = 'ko' } = getQuery<{ locale?: string }>(event)
  return { locale }
})

파일 업로드처럼 새 surface에 없는 기능은 현재처럼 h3를 쓸 수 있습니다. 검증: 같은 API에 unit test와 실제 SSR 요청을 붙이고, auto-import와 새 import를 의도치 않게 섞었을 때 나오는 NUXT_E8012 오류가 없는지 typecheck에서 확인하세요.

2. 세션은 비밀값 하나를 더 엄격히 다루게 합니다

변화: 4.6은 runtimeConfig.appSecret과 NUXT_APP_SECRET, 그리고 cookie에 sealed session을 저장하는 useSession helper를 추가했습니다. 모듈과 서버 기능은 deriveSecret(purpose)로 목적별 값을 파생할 수 있습니다. 실제 영향: 별도 서버 저장소 없이 작은 세션 기능을 만들 수 있지만, app secret이 바뀌면 기존 세션은 읽지 못할 수 있습니다. 개발에서는 값이 생성·유지될 수 있어도 build는 생성하지 않습니다. 적용 조건: 운영 시크릿은 CI/CD secret store에서 주입하고, 스테이징·운영 값을 분리하세요. nuxt.config.ts, 로그, PR 설명에 값을 쓰지 않습니다. 검증: 배포 전 새 값을 가진 preview 환경에서 로그인·로그아웃·만료·키 회전 뒤의 실패 동작을 시험하고, cookie의 Secure·HttpOnly·SameSite 설정을 브라우저와 curl로 확인합니다.

3. typed `$fetch`는 큰 API 트리의 CI 시간을 바꿀 수 있습니다

변화: Nuxt는 서버 route 타입 생성을 fetchdts 기반으로 다시 만들었고, 4.x에서는 experimental.routeTypedFetch: true로 선택 적용합니다. 공식 수치는 1,000 routes에서 이전 방식이 TS2589와 함께 약 7.44초·1,283만 인스턴시에이션이던 예가 새 방식에서는 약 0.20초·5.1만으로 줄었다고 보여 줍니다. 이는 Nuxt 팀 벤치마크이지 모든 저장소의 보장치는 아닙니다. 실제 영향: body·query 검증 정보가 호출부 타입으로 이어져 잘못된 POST body를 더 일찍 잡을 수 있습니다. 적용 조건: 큰 앱에서만 별도 브랜치로 켜고, 손으로 만든 ServerRoutes augmentation과 Date 직렬화 가정을 점검하세요. 검증: nuxi typecheck 시간과 오류 수를 업그레이드 전후 비교하고, 대표 server/api 호출에 잘못된 body·없는 route의 컴파일 실패 테스트를 추가합니다.

4. CLI v4의 관찰 기능은 개발 편의가 아니라 재현 속도 문제입니다

변화: CLI v4는 요청마다 ID를 붙이고, 시작이 느린 이유·재시작 원인·모듈 설정 시간을 보여 주며, source map을 적용한 SSR 오류 화면을 제공합니다. 실제 영향: “로컬에서 한 번만 500이 났다”는 버그를 middleware·data fetch·렌더의 한 요청 타임라인으로 좁히기 쉬워집니다. 하지만 dev 오류 화면에는 요청 정보가 있을 수 있으므로 외부에 열린 개발 서버를 운영 도구처럼 취급하면 안 됩니다. OpenAI 에이전트나 다른 자동화가 두 번째 nuxt dev를 실행하는 환경도 새 lock file 동작을 이해해야 합니다. 적용 조건: CI 로그 파서는 TUI 출력에 의존하지 않게 하고 CI에는 plain 모드를 씁니다. 검증: 의도적인 SSR 예외와 nuxt.config.ts 오류 fixture를 만들어 로컬 개발·CI·preview에서 오류 내용과 비밀 마스킹이 기대대로인지 확인하세요.

개발자 실행 계획

P0: CI와 배포 image의 Node 버전을 확인해 4.6 요구 범위를 만족시키고 lockfile을 보존합니다.
P0: server/api, server/middleware, Nuxt module에서 h3/nitropack 직접 import를 검색해 목록화합니다.
P1: read-only API 한 개만 nuxt/server 명시 import로 옮겨 unit test·SSR smoke test를 통과시킵니다.
P1: NUXT_APP_SECRET의 운영 주입·회전·롤백 책임자를 정하고 저장소와 로그에 값이 없는지 확인합니다.
P1: 큰 route 수가 있는 앱에서만 routeTypedFetch를 분리 브랜치로 켜고 typecheck 시간과 타입 오류를 비교합니다.
P2: npx nuxt upgrade --dedupe 후 clean install, nuxi typecheck, build, SSR·로그인·API e2e를 CI 필수 단계로 둡니다.
P2: future.compatibilityVersion: 5은 production이 아닌 nightly/호환성 브랜치에서만 검증합니다.

리스크와 한계

4.6은 Nuxt 4 사용자에게 강제 migration을 요구하지 않지만, Node 범위와 CLI major가 함께 바뀝니다. CI runner가 이전 Node에 고정돼 있거나 module이 내부 H3 event를 가정하면 build가 먼저 실패할 수 있습니다. 새 nuxt/server helper는 H3 v1 이름과 완전히 같은 동작이 아닙니다. 예를 들어 redirect 반환과 response header 설정 방식이 다릅니다. 문제 발생 시 이전 검증 image와 lockfile로 롤백하고, 모든 handler를 되돌리기보다 변경 파일만 분리해 재현하세요. Nuxt 5와 Vite server는 미래 호환성 방향이지 이번 릴리스에서 운영 기본값으로 확정된 것은 아닙니다.

FAQ

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

아닙니다. 기존 H3·Nitro import는 계속 동작합니다. 새 코드와 공용 모듈부터 시작하고, 파일 업로드처럼 필요한 H3 기능은 그대로 두는 편이 안전합니다.

Nuxt 4.6의 appSecret은 기존 JWT나 세션 DB를 대체하나요?

작은 sealed-cookie session을 만들 수 있는 기반을 제공하지만 모든 인증 구조의 대체품은 아닙니다. 권한 모델, 로그아웃 무효화, 다중 기기 관리, 개인정보 보관 요구에 맞는지 별도로 판단해야 합니다.

routeTypedFetch는 바로 production에 켜도 될까요?

4.x에서는 선택 기능입니다. 대형 route 트리에서 효과가 클 수 있지만 type inference와 손수 만든 타입 확장이 달라질 수 있으니 별도 브랜치에서 typecheck와 대표 API 호출을 먼저 검증하세요.

출처 및 추가 읽기

더 깊게 읽기: 실전 가이드

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