Nuxt 4.6 서버 경계와 CI 점검 | Nuxt 4.6 Server Boundaries and CI Checks

핵심 답변: Nuxt 4.6으로 올릴 팀이 이번 주 가장 먼저 확인할 것은 새 CLI 화면이 아니라 서버 코드를 어디에서 가져오는지입니다. 2026년 10월 5일 공개된 Nuxt 4.6은 nuxt/server라는 서버 유틸리티 진입점을 내세워 Nitro·H3의 내부 버전과 앱 코드를 분리하기 시작했습니다. 동시에 Nuxt CLI v4가 함께 들어오므로, 개발 서버를 자동으로 띄우는 CI·에이전트·로컬 스크립트의 동작도 다시 봐야 합니다.

이미 Nuxt 4를 쓰는 프로젝트에는 매력적인 업데이트입니다. 다만 server/api에서 h3나 nitropack를 직접 가져오고, .nuxt 디렉터리를 CI 캐시처럼 다루거나, 포트 위에서 여러 nuxt dev를 돌리는 환경이라면 단순한 lockfile 갱신으로 끝내면 안 됩니다. Nuxt 3은 2026년 7월 31일 지원 종료(EOL)에 도달했으므로 아직 3.x라면 보안 패치만 기다리는 전략도 더 이상 안전하지 않습니다.

이 글은 “지금 바로 4.6으로 가라”는 안내가 아닙니다. 실제 Nuxt 앱에서 import 경계를 정리하고, 개발 도구 자동화가 충돌하지 않는지 확인하고, SSR·배포·보안 회귀를 잡는 순서입니다. 새 기능은 스테이징에서 관찰한 뒤 제한적으로 넓히는 편이 빠른 롤백보다 보통 더 싸게 끝납니다.

무슨 일이 있었나

Nuxt 팀은 2026년 10월 5일 Nuxt v4.6.0 릴리스 노트를 공개했습니다. 이 릴리스에는 @nuxt/cli v4가 의존성으로 포함됩니다. 릴리스 노트에 따르면 새 CLI는 개발 서버의 상태·로그·라우트·네트워크 요청을 보는 터미널 UI, .nuxt/의 lock file, 실행 중인 서버와 통신하는 nuxt curl·nuxt task, 그리고 nuxt preview --takeover를 제공합니다. Node.js는 v22.21+, v24.11+ 또는 v26+가 필요하다고 명시했습니다.

더 큰 변화는 서버 의존성 경계입니다. Nuxt는 nuxt/server에서 앱에 필요한 서버 유틸리티와 타입을 노출하고, 요청 이벤트·route rules·typed $fetch에 자체 타입 표면을 정의하기 시작했습니다. 기본 구현은 여전히 Nitro지만, 앱과 모듈이 특정 H3/Nitro 메이저 버전에 직접 묶이는 문제를 줄이려는 방향입니다. 순수 Vite 서버 빌드인 @nuxt/vite-server도 실험적으로 언급됐지만, 릴리스 노트는 대부분의 사용자에게 Nitro가 여전히 맞는 선택이라고 말합니다.

이번 변화는 7월 18일의 Nuxt 4.5와 이어서 봐야 합니다. 4.5는 Vite 8, Rspack 2, 실험적 SSR streaming, 안정적인 오류 코드를 도입했습니다. 그리고 7월 27일의 보안 패치 공지는 Nuxt 4.5.1·3.21.10 및 @nuxt/devtools 3.3.1 업데이트를 권고했습니다. 오래된 Nuxt 3 또는 4.4 계열을 그대로 두고 4.6의 개발 경험만 부러워할 상황은 아닙니다.

왜 중요한가

Nuxt 애플리케이션은 프런트 코드만으로 끝나지 않습니다. server/api, SSR 렌더링, middleware, routeRules, Nitro preset, CI의 빌드 캐시가 한 덩어리로 움직입니다. 서버 구현체를 직접 import한 코드는 프레임워크가 H3나 Nitro를 올릴 때 타입 충돌과 런타임 차이를 먼저 맞습니다. nuxt/server로 옮겨 갈수록 프레임워크가 약속한 표면 위에서 앱을 유지할 수 있습니다.

개발 서버의 lock과 takeover도 운영 이슈입니다. 개발자가 켜 둔 nuxt dev 위에 IDE 에이전트나 e2e 스크립트가 두 번째 서버를 띄우면 포트만 충돌하는 문제가 아니었습니다. 서로 다른 .nuxt 산출물을 읽고, 환경 변수를 섞거나, 어느 로그가 어느 프로세스 것인지 잃는 일이 생깁니다. CLI v4의 도입은 이런 자동화가 새 동작을 제대로 따르는지 검증할 계기입니다.

server/api의 직접 import를 먼저 찾기

가장 작은 첫 작업은 코드 검색입니다. server/, 모듈, 레이어에서 from 'h3', from 'nitropack', 내부 #internal 경로를 찾아 목록을 만드세요. 모든 import를 기계적으로 바꾸기보다, Nuxt가 공개한 nuxt/server 대체물이 있는지 하나씩 확인합니다. 예를 들어 이벤트·응답·라우팅 타입을 앱이 직접 구현체에 묶어 쓰고 있다면 공용 어댑터 파일을 하나 두고 그곳에서만 전환하는 편이 PR 범위를 줄입니다.

검증은 타입 검사와 실제 요청을 같이 해야 합니다. nuxi typecheck가 통과해도 SSR에서 cookie를 설정하거나 오류 status를 바꾸는 API는 런타임에서 다르게 보일 수 있습니다. server/api/session.get.ts, 인증된 server/api/me.get.ts, 파일 업로드 endpoint를 대상으로 200·401·429·500 응답 헤더까지 스냅샷 테스트하세요. E2E는 브라우저만 보지 말고 curl로 JSON과 Set-Cookie를 확인하는 것이 좋습니다.

CLI v4와 CI/CD의 개발 서버를 분리하기

CLI v4의 .nuxt lock은 두 번째 nuxt dev가 기존 서버를 인식할 수 있게 합니다. 로컬에서 에이전트가 개발 서버를 띄우는 팀은 특히 이 동작을 알아야 합니다. 기존 스크립트가 포트를 점유한 프로세스를 무조건 죽인 뒤 다시 올렸다면, 새 서버가 이미 존재하는 경우와 --takeover가 필요한 경우를 나눠야 합니다. 반대로 CI는 개발 서버를 공유하지 않는 깨끗한 workspace에서 nuxi build와 nuxi preview를 실행하도록 두는 편이 재현성이 높습니다.

package.json의 e2e 명령에는 시작 명령, health endpoint, 종료 책임을 명확히 적으세요. 예를 들어 /api/health가 200을 반환한 뒤 Playwright를 시작하고, 테스트가 끝나면 해당 PID만 종료합니다. .nuxt 전체를 캐시한다면 Node 버전, Nuxt 버전, lockfile hash를 캐시 키에 넣고 버전이 달라지면 폐기하세요. 빌드 산출물을 오래 재사용해 생기는 오류는 CLI 속도 개선으로 해결되지 않습니다.

SSR streaming은 TTFB보다 응답 변경 경로를 먼저 보기

Nuxt 4.5의 experimental ssrStreaming은 HTML shell을 먼저 보내 TTFB를 낮출 수 있습니다. 그러나 스트리밍이 시작된 뒤에는 HTTP status와 header를 바꿀 수 없습니다. 공식 블로그도 <script setup>에서의 setResponseStatus(), middleware 중 cookie 쓰기 같은 후반 변경이 클라이언트에 반영되지 않을 수 있다고 설명합니다. redirect, cache, ISR, SWR, ssr: false routeRules에는 자동 폴백이 있지만, 앱의 모든 경로를 대신 검사해 주지는 않습니다.

따라서 콘텐츠 목록처럼 읽기 중심인 route에서만 시작하세요. nuxt.config.ts에 streaming을 켜기 전, 인증 middleware·A/B cookie·지역 redirect·에러 페이지를 표로 만들고 각 경로에서 첫 바이트 이후 어떤 헤더 변경이 있는지 찾습니다. Googlebot 등 봇에는 완전 렌더링된 HTML을 주는 기본 동작이 있어도, 실제 배포 URL에서 robots와 OG 메타가 유지되는지 Lighthouse와 curl로 확인해야 합니다.

Nuxt 3 EOL과 보안 패치는 별개의 체크포인트

Nuxt 3 지원 종료는 ‘당장 빌드가 깨진다’는 뜻은 아니지만, 새 보안 수정이 계속 제공된다는 기대를 버려야 한다는 뜻입니다. 특히 공식 보안 권고에는 route middleware만으로 보호한 .server.vue 페이지가 /__nuxt_island/ 경로에서 우회될 수 있었던 사례가 있습니다. GHSA-hg3f-28rg-4jxj는 영향을 받는 버전과 패치 버전을 명시합니다.

중요한 교훈은 버전 숫자만 올리라는 것이 아닙니다. 인증은 middleware/auth.ts만 믿지 말고 server/api의 데이터 조회 지점에서도 세션과 권한을 검증해야 합니다. pages/admin.server.vue 같은 파일이 있다면 직접 island endpoint를 요청하는 회귀 테스트를 넣고, 비인가 요청에서 HTML 조각이나 사용자 데이터가 나오지 않는지 확인하세요. routeRules는 편리한 배포 설정이지 민감 데이터의 유일한 방어선이 아닙니다.

관찰 가능한 업그레이드로 끝내기

Nuxt 4.6 업그레이드는 한 번의 빌드 성공보다 배포 뒤 관찰이 중요합니다. 서버 import를 바꾼 뒤에는 SSR 오류율, API p95, hydration warning, 404 비율을 이전 릴리스와 비교하세요. CLI의 더 빠른 초기 표시 시간은 로컬 체감에 도움이 되지만, 실제 CI 총시간은 의존성 설치, typecheck, prerender, 캐시 적중 여부에 따라 달라집니다. 각각을 분리해 기록하지 않으면 무엇이 개선됐는지 알 수 없습니다.

롤백은 package manager의 lockfile과 이전 컨테이너 이미지로 할 수 있게 준비합니다. database migration과 프레임워크 업그레이드를 같은 배포에 섞지 말고, canary 환경에 먼저 넣어 SSR 페이지·서버 API·이미지 최적화·배포 preset을 한 번씩 통과시키세요. 오류 코드가 안정화된 4.5 계열의 장점도 여기서 살아납니다. 에러 코드와 요청 ID를 alert에 포함하면 로그에서 원인을 훨씬 빨리 좁힐 수 있습니다.

개발자 실행 계획

node --version으로 CI와 개발 컨테이너가 Nuxt 4.6 요구 버전(v22.21+, v24.11+, v26+)을 만족하는지 확인합니다.
server/와 모듈의 h3·nitropack 직접 import 목록을 만들고 공개 nuxt/server API로 바꿀 후보를 표시합니다.
별도 브랜치에서 npx nuxt upgrade --dedupe 후 lockfile diff와 custom Vite/Rspack 플러그인을 리뷰합니다.
인증 API, cookie, redirect, 오류 응답에 curl 기반 SSR 회귀 테스트를 추가합니다.
개발 서버를 띄우는 IDE·에이전트·Playwright 스크립트가 CLI v4 lock 및 종료 책임을 지키는지 확인합니다.
experimental.ssrStreaming은 콘텐츠 route 한 곳에서만 canary로 켜고 TTFB·status·header·SEO HTML을 비교합니다.
.server.vue와 /__nuxt_island/ 노출 경로를 검사하고 서버 데이터 계층에서도 권한을 검증합니다.
배포 후 7일간 SSR 오류율, API p95, hydration warning, 401/403 비율을 이전 버전과 비교하고 롤백 기준을 적용합니다.

리스크와 한계

Nuxt 4.6의 서버 비종속성은 방향과 공개 API를 제공하는 변화이지, 모든 H3/Nitro 코드를 한 번에 없애도 된다는 보장은 아닙니다. 쓰는 모듈, 배포 adapter, 커스텀 server preset에 따라 호환성 점검이 필요합니다. 실험적 @nuxt/vite-server와 SSR streaming은 기본 Nitro 구성을 바꾸기 전에 격리 환경에서 검증해야 합니다.

CLI v4의 성능 수치는 공식 릴리스 노트의 비교 환경 수치입니다. 개발자의 Mac, 모노레포 크기, 바이러스 검사, 원격 파일 시스템, CI 캐시에서는 다르게 나올 수 있습니다. 롤백 조건은 build 실패만이 아닙니다. SSR 5xx 증가, 인증 우회 징후, 헤더 누락, 이미지·CSS flash, 배포 preset의 cold start 급증이 보이면 이전 lockfile과 이미지로 되돌리고 원인을 분리하세요.

FAQ

Nuxt 3 프로젝트는 Nuxt 4.6으로 바로 올려야 하나요?

Nuxt 3은 지원 종료 상태이므로 마이그레이션 계획은 서둘러야 합니다. 다만 production에서 즉시 메이저 업그레이드하기보다 공식 Upgrade Guide와 스테이징 회귀 테스트를 거쳐 4.x의 지원 버전으로 옮기세요. 보안 문제는 마이그레이션과 별도로 현재 지원되는 패치 수준인지 먼저 확인해야 합니다.

Nuxt 4.6의 nuxt/server는 기존 h3 import를 전부 대체하나요?

Nuxt가 앱에 필요한 공개 서버 표면을 제공하려는 방향입니다. 실제 대체 가능 여부는 사용하는 함수와 모듈에 따라 다르므로, 직접 import를 찾아 공식 API와 대조한 뒤 어댑터 단위로 바꾸는 것이 안전합니다.

SSR streaming을 켜면 Nuxt SEO가 나빠지나요?

공식 설명상 봇과 crawler에는 스트리밍이 자동 비활성화되어 완전 렌더 HTML을 받습니다. 그래도 프로젝트의 bot regex, 캐시, redirect, meta 태그가 얽힐 수 있으므로 실제 공개 URL의 HTML과 Search Console 관찰을 검증해야 합니다.

출처 및 추가 읽기

더 깊게 읽기: 실전 가이드

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