Nuxt 4.6·4.6.1: CLI v4와 server-agnostic 전환 전에 점검할 SSR·CI·보안

핵심 답변: 10월 5일 공개된 Nuxt 4.6과 10월 9일의 4.6.1은 단순 패치 묶음이 아닙니다. 개발 서버를 바라보는 방식, 서버 코드를 배포 대상에서 떼어내는 방식, 타입이 있는 $fetch와 서버 라우트의 연결이 바뀌는 릴리스입니다. Nuxt 4를 운영 중이라면 이번 주에는 업그레이드 버튼보다 먼저 Node 버전, nuxt.config.ts, CI가 실행하는 dev·build·preview 경로를 확인하는 편이 안전합니다.

4.6은 새 Nuxt CLI v4를 함께 가져옵니다. 터미널에서 요청·오류·재시작 이유를 보여주고, .nuxt/의 잠금 파일을 통해 두 번째 nuxt dev가 기존 서버를 넘겨받거나 기다릴 수 있습니다. 로컬에서 개발자와 AI 에이전트가 같은 프로젝트를 만지는 팀에는 꽤 실무적인 변화입니다. 4.6.1은 이어서 Vite 8.1+ 의존성 힌트, virtual import, SSR lifecycle, nitropack/types 해석 같은 개발·빌드 경로의 오류를 고쳤습니다.

다만 업데이트만으로 안전해지는 것은 아닙니다. Nuxt는 7월의 보안 패치에서 server islands, routeRules, 캐시된 _payload.json, DevTools 문제를 수정했습니다. 아직 그 패치 계열을 반영하지 않았다면 4.6 탐색보다 보안 업데이트와 CDN 캐시 점검이 우선입니다. 이번 글은 새 기능을 무작정 적용하기보다, SSR 서비스에서 실제로 어떤 파일과 테스트를 확인할지에 초점을 맞춥니다.

무슨 일이 있었나

Nuxt 팀은 2026년 10월 5일 Nuxt 4.6.0을 발표했습니다. 공식 블로그에 따르면 이번 마이너 릴리스는 4.5.2 이후 362개 이상 커밋을 포함하며, 서버에 덜 묶인 Nuxt를 향한 첫 단계로 nuxt/server, 다시 구성한 typed $fetch, 세션, Vue Vapor 지원, 개발 오류 화면을 담았습니다. 함께 배포된 Nuxt CLI v4는 nuxt dev의 인터랙티브 터미널 UI, 요청 ID, 재시작 원인·모듈 초기화 시간 표시, nuxt curl·nuxt task·nuxt docs 명령을 제공합니다.

CLI v4는 Nuxt 의존성으로 포함되므로 Nuxt를 올리면 같이 들어옵니다. 공식 비교 수치는 CLI 설치 크기 13.1MB에서 3.5MB, Linux 유휴 메모리 630MB에서 440MB로의 감소를 제시하지만, 이는 Nuxt 팀 측정 환경의 수치입니다. 각 프로젝트의 모듈 수, Node 버전, 파일 감시 환경에서 같은 결과가 난다고 단정할 수는 없습니다. 또한 4.6은 Node.js ^22.22.3 || ^24.15.0 || >=26.0.0을 요구합니다.

10월 9일 Nuxt 4.6.1은 후속 패치입니다. portable event의 web view를 첫 접근 때 만들도록 바꿨고, Vite 8.1+ optimizer 메시지, 설치된 패키지의 virtual import로 인한 dependency scan 중단, non-SSR 환경의 outDir, useId hydration과 onServerPrefetch 보존, nitropack/types의 nodenext 해석 등을 수정했습니다. 즉 새 기능보다 빌드·개발 서버·SSR 경계의 안정화가 중심입니다.

왜 중요한가

Nuxt 앱은 pages/와 컴포넌트만으로 끝나지 않습니다. server/api에서 인증을 처리하고, routeRules로 캐시를 설정하며, SSR 결과를 CDN에 보내고, CI에서 build와 preview를 검증합니다. 4.6의 server-agnostic 방향은 이런 서버 코드를 특정 런타임 가정에서 분리할 기회를 주지만, 동시에 Node API·플랫폼 전용 헤더·배포 어댑터 의존을 찾아내야 한다는 뜻입니다.

개발 경험 변화도 운영에 닿습니다. 요청 ID와 오류 원인이 잘 보이면 로컬에서 재현한 SSR 오류를 로그와 연결하기 쉬워집니다. 반면 개발 서버 잠금과 takeover는 동시에 여러 프로세스를 띄우는 CI, IDE task, 코딩 에이전트에서 포트·상태를 어떻게 관리할지 다시 점검하게 합니다. “더 편해졌다”는 이유만으로 기존 스크립트를 바꾸지 말고, 실제 개발·테스트 루프에서 충돌이 없는지 확인해야 합니다.

Nuxt CLI v4: 로그를 보는 습관을 요청 단위로 바꿉니다

기존에는 nuxt dev 출력이 길어지면 어느 요청이 오류를 만들었는지 추적하기 어려웠습니다. CLI v4는 요청마다 ID를 붙이고, URL·재시작 이유·느린 시작 구간·모듈 초기화 시간을 보여줍니다. 예를 들어 server/api/products/[id].get.ts에서만 500이 발생한다면, 브라우저 네트워크 탭과 터미널의 같은 요청 ID를 연결해 재현 시간을 줄일 수 있습니다.

팀 공통 스크립트는 바로 바꾸지 말고 package.json의 dev, dev:ci, preview를 따로 실행해 보십시오. 로그를 텍스트로 수집하는 자동화가 있다면 --no-tui가 필요한지도 확인합니다. 두 번째 dev 서버를 띄우는 테스트 도구나 에이전트가 있다면 .nuxt/ 잠금 파일의 takeover·defer 동작을 로컬에서 먼저 관찰하는 것이 좋습니다.

nuxt/server와 portable event: 서버 코드를 이식 가능하게 만드는 출발점입니다

Nuxt 4.6의 nuxt/server는 서버 코드를 더 이식 가능한 이벤트 모델 위에 놓는 방향입니다. 이는 당장 모든 server/api 파일을 옮기라는 지시가 아닙니다. 먼저 Node 전용 fs, raw socket, 특정 프록시 헤더처럼 배포 대상에 묶인 코드를 찾아 경계를 분명히 하라는 신호에 가깝습니다. Cloudflare, Node 서버, 서버리스 런타임을 섞어 쓰는 조직일수록 이 작업의 가치가 큽니다.

파일럿으로 읽기 전용 API 하나를 고르십시오. 예를 들어 server/api/health.get.ts 또는 인증 없는 콘텐츠 조회 라우트가 적합합니다. Node와 preview 배포에서 상태 코드, JSON 본문, cache-control, 오류 응답이 같은지 계약 테스트로 비교합니다. 파일 업로드, 세션, 스트리밍, 데이터베이스 트랜잭션처럼 런타임 특성이 큰 경로는 이후 단계로 미루는 편이 안전합니다.

typed $fetch: 편리함은 생성된 라우트와 CI가 같이 맞을 때 유지됩니다

공식 릴리스 노트는 생성된 서버 라우트에서 $fetch와 useFetch의 타입을 강화한다고 설명합니다. 프론트엔드에서 await $fetch('/api/users')를 쓸 때 응답과 메서드 오류를 더 이르게 잡을 가능성이 생기지만, 타입 생성물이 오래되었거나 monorepo의 tsconfig 경로가 꼬이면 빌드와 에디터가 다른 결론을 낼 수 있습니다. 4.6.1의 nitropack/types nodenext 수정도 이런 경계가 실제로 문제였음을 보여줍니다.

업그레이드 PR에서는 nuxi prepare 또는 프로젝트의 타입 생성 단계가 CI에서 실행되는지 확인하고, vue-tsc --noEmit과 production build를 모두 돌리십시오. server/api의 응답 타입을 암묵적으로 any로 넘기는 곳은 이번 기회에 명시해 두면, 이후 라우트 변경에서 클라이언트 오류를 더 일찍 찾을 수 있습니다.

4.6.1의 빌드·SSR 수정: 개발에서만 고치지 말고 preview까지 봅니다

4.6.1은 virtual import가 설치된 패키지에 있을 때 dependency scan을 중단하지 않도록 고쳤고, non-SSR target에서 설정한 outDir를 public directory로 사용하도록 조정했습니다. 또한 useId hydration 전의 onServerPrefetch를 보존하고, dev server handler에는 RequestEvent를 넘깁니다. 모듈을 많이 쓰거나 SSR과 SPA target을 함께 운용하는 앱이라면 “로컬 dev가 켜진다”만으로 충분하지 않습니다.

nuxt build 뒤 nuxt preview에서 로그인 전·후 페이지, dynamic import, 에러 페이지, API proxy를 확인하십시오. SSR 페이지라면 서버 HTML과 hydration 후 DOM이 달라지지 않는지, 에러 수집 도구의 stack trace가 원본 소스 위치를 가리키는지 봅니다. static target을 가진 서비스는 설정한 nitro.output.publicDir과 CDN 업로드 경로가 그대로인지 배포 산출물 diff로 검증하는 편이 낫습니다.

보안 패치와 routeRules: 4.6 계획보다 먼저 남은 노출을 닫습니다

Nuxt의 보안 패치 안내는 4.5.1과 3.21.10에서 server island props RCE, route rule authorization bypass, server component DoS, 캐시된 페이지의 교차 사용자 payload 노출, dev server 경로 노출, DevTools RCE를 고쳤다고 밝힙니다. 특히 대문자가 있는 routeRules 키에 appMiddleware를 권한 게이트로 쓴 경우, 기본 대소문자 비구분 라우팅에서 규칙이 건너뛰어질 수 있었습니다.

nuxt.config.ts의 routeRules과 pages/Admin.vue처럼 대문자가 섞인 파일명을 검색해 보십시오. 인증된 페이지에 cache, swr, isr을 적용했다면 업그레이드 후 CDN·edge에 남은 _payload.json도 정리해야 합니다. 이 항목은 새 4.6 기능의 장점보다 먼저 해결할 운영 위험입니다.

개발자 실행 계획

런타임을 고정합니다. CI와 배포 이미지의 Node가 4.6 요구 범위인지 node -v, .nvmrc, Dockerfile에서 확인합니다.
업그레이드를 분리합니다. npx nuxt upgrade --dedupe를 기능 변경 PR과 섞지 않고 lockfile diff를 리뷰합니다.
dev 스크립트를 점검합니다. nuxt dev, 로그 수집용 --no-tui, 두 번째 프로세스의 takeover 동작을 확인합니다.
타입 생성과 빌드를 CI에 둡니다. prepare·typecheck·production build·preview smoke test를 같은 PR에서 실행합니다.
SSR 경로를 테스트합니다. 로그인, redirect middleware, useAsyncData, dynamic import, hydration 오류를 실제 preview URL에서 확인합니다.
서버 이식성은 하나부터 시작합니다. 읽기 전용 server/api 라우트 하나를 골라 Node·preview 배포의 응답 계약을 비교합니다.
보안 설정을 재검토합니다. routeRules 대소문자, authenticated cache, DevTools, server islands와 CDN payload purge 절차를 확인합니다.

리스크와 한계

4.6의 CLI 성능 수치는 공식 비교 환경의 결과이며 모든 앱의 CI 시간이나 메모리 감소를 보장하지 않습니다. nuxt/server는 이식성을 위한 기반이지, 기존 Node 전용 라이브러리를 자동으로 호환시키는 기능도 아닙니다. 따라서 새 런타임으로의 전환은 API 하나씩 canary 배포하고 상태 코드·지연 시간·오류율을 비교해야 합니다.

업그레이드 뒤 hydration 오류, 서버 route 타입 오류, preview에서만 보이는 자산 경로 문제가 나오면 lockfile과 Node 버전을 포함해 직전 검증된 버전으로 되돌릴 수 있어야 합니다. 인증 페이지의 캐시나 routeRules 권한 경로가 바뀌면 즉시 롤백·캐시 purge 조건으로 삼으십시오. 아직 적용하지 않은 보안 패치가 있다면 기능 실험보다 그 업데이트를 먼저 별도 PR로 처리하는 편이 낫습니다.

FAQ

Nuxt 4.6으로 올리면 Nuxt CLI v4도 따로 설치해야 하나요?

아닙니다. 공식 발표에 따르면 @nuxt/cli v4는 Nuxt 의존성으로 함께 설치됩니다. 다만 팀 스크립트와 CI 로그 수집이 새 TUI 출력에 영향을 받는지 확인해야 합니다.

Nuxt 4.6의 Node.js 최소 버전은 무엇인가요?

공식 블로그 기준 ^22.22.3 || ^24.15.0 || >=26.0.0입니다. 로컬뿐 아니라 CI runner와 production image까지 같은 범위를 맞추십시오.

routeRules를 쓰는 Nuxt 앱은 무엇을 점검해야 하나요?

대문자가 들어간 규칙 키와 페이지 경로, appMiddleware 기반 권한 처리, 인증 페이지의 cache·swr·isr을 우선 점검하십시오. 보안 패치 후에는 CDN의 기존 payload도 purge해야 할 수 있습니다.

출처 및 추가 읽기

더 깊게 읽기: 실전 가이드

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

Nuxt 4.6·4.6.1: CLI v4와 server-agnostic 전환 전에 점검할 SSR·CI·보안 | Nuxt 4.6/4.6.1 Operations