H3 v2와 Nitro main 변화로 보는 Nuxt 런타임 전환점 | Nuxt Runtime Transition: H3 v2 and Nitro Main Changes

요약: 2026년 10월 3~5일 Nuxt 프론트엔드 생태계의 핵심은 H3 v2 정식 출시와 이를 받아들이는 Nitro main 브랜치의 런타임·빌드·개발 프록시 변화다. Nuxt/Vue/Vite의 새 안정판은 이 72시간 창에서 확인되지 않았지만, 서버 경계와 개발 환경의 계약이 바뀌는 신호가 반복됐으므로 실제 업그레이드는 릴리즈 노트를 기다리되 테스트 기준은 지금 준비할 가치가 있다.

3일 결론

지금 Nuxt 앱을 즉시 대규모 업그레이드할 근거는 아니다. 다만 H3 v2가 정식화되고 Nitro의 main 브랜치가 H3 v2, 공통 빌드 플러그인, WebSocket 프록시를 동시에 다루기 시작했다. 따라서 프론트엔드 팀은 Node 런타임 하한, API 오류 응답, 개발 프록시, 번들 플러그인 경계를 분리해 회귀 테스트로 고정해야 한다. 아래 Nitro/Nuxt 변경은 main 브랜치의 미출시 작업이며 배포 가능한 릴리즈로 간주하면 안 된다.

이번 72시간에 확인한 핵심 이슈 6개

H3 v2.0.1 정식: 10월 3일 v2가 stable로 배포됐다. 표준 Request/Response/URL/Headers 위의 재작성, 범용 런타임, 라우트 규칙·검증·WebSocket 유틸리티가 핵심이다.
Node 요구사항: H3 v2의 Node 실행 조건은 >=20.19다. CI, 로컬 개발, 배포 런타임이 서로 다른 Node 버전을 쓰면 이행 자체가 실패할 수 있다.
Nitro main의 H3 v2 동기화: 10월 3일 Nitro는 H3 v2 업데이트 커밋을 반영했다. 이는 Nuxt 서버 계층의 차기 호환성 신호이지, 현재 Nuxt 프로젝트에 강제되는 안정 릴리즈 공지는 아니다.
Nitro main의 buildPlugins: Vite, Rollup, Rolldown, builder: false에 공통으로 적용할 빌드 플러그인 옵션이 추가됐다. 도구별 플러그인 경계를 명시하려는 아키텍처 변화다.
Nitro main의 devProxy WebSocket: ws: true가 붙은 devProxy 규칙에서 upgrade 요청을 프록시하도록 보완됐다. 실시간 백엔드와 Nuxt 개발 서버를 함께 쓰는 팀에 직접 관련된다.
Nuxt main의 오류 응답 계약: 페이지 렌더 오류는 HTML 오류 페이지, server route/middleware 오류는 JSON으로 반환하도록 명확히 하는 breaking 변경이 올라왔다. 같은 URL에 Accept 헤더별 서로 다른 응답이 생기는 문제를 줄이는 방향이다.

흐름 1 — H3 v2 정식화: 서버 코드를 웹 표준 계약으로 재점검

확인된 사실

H3 v2.0.1 릴리즈는 v2를 정식으로 선언했다. 핸들러는 표준 요청·URL을 다루고, 값·스트림·Response 등을 응답으로 변환한다. 또한 Node, Bun, Deno, Cloudflare Workers, Service Worker, 브라우저를 대상으로 하는 런타임 모델과 h3/rules 기반 헤더·리다이렉트·CORS·캐시·프록시 규칙을 제시한다.

Nuxt 개발자에게 중요한 이유

Nuxt의 서버 기능은 Nitro/H3 경로와 만난다. 따라서 서버 핸들러가 Node 전용 request/response 객체, 비표준 헤더 처리, 암묵적 런타임 전제에 기대고 있다면 H3 v2 계열을 채택하는 시점에 이식성·타입·테스트 문제가 드러날 수 있다. 이것은 성능 수치를 보장하는 발표가 아니라, 런타임 계약을 표준화하는 기술적 기반 변화로 읽어야 한다.

실무 판단: production 의존성을 지금 바꾸기보다, Node 20.19 이상인 별도 CI 매트릭스에서 API 핸들러·스트리밍·쿠키·에러 응답을 검증한다. H3의 공식 마이그레이션 가이드로 deprecated API와 새 이벤트 모델을 대조한다.

흐름 2 — Nitro main: 빌드 확장 지점과 실시간 개발 프록시를 분리

공통 buildPlugins는 도구 종속성을 드러낸다

10월 3일의 Nitro main 커밋은 buildPlugins를 추가했다. 문서상 Vite에서는 서버 번들(Nitro 환경)에 적용되고 Vite 자체 플러그인은 여전히 Vite의 plugins를 사용한다. Rollup/Rolldown/Vite/unbundled 환경에 공통으로 적용할 훅은 resolveId, load, transform처럼 이식 가능한 범위로 제한된다.

시사점: 변환 로직을 “클라이언트 개발 서버 전용”과 “서버 번들 공통”으로 구분해야 한다. 향후 이 옵션이 릴리즈되어도 기존 Vite 플러그인을 무조건 옮기지 말고, SSR 산출물에 필요한 최소 transform만 공통 계층으로 추출하는 편이 안전하다.

WebSocket devProxy 보완은 로컬 통합 테스트 대상

10월 4일 Nitro main 커밋은 devProxy의 ws: true 규칙이 WebSocket upgrade를 처리하도록 보완하고, 와일드카드 경로와 비매칭 요청을 테스트한다. 이는 릴리즈 전 변경이다. 그러나 Nuxt 앱이 알림·협업·AI 스트리밍 같은 소켓 백엔드를 로컬에서 프록시한다면, HMR 연결과 앱 소켓 연결이 서로 침범하지 않는지 확인할 구체적인 체크포인트가 된다.

흐름 3 — Nuxt main의 오류 형식: 페이지와 API를 같은 실패로 취급하지 말 것

10월 4일 Nuxt main 커밋은 페이지 렌더 오류는 HTML 오류 페이지로, server route와 server middleware 오류는 JSON으로 반환하도록 문서와 구현을 바꿨다. 해당 커밋은 breaking 표시가 된 미출시 main 변경이다. 핵심은 Accept 헤더나 /api/ 접두어가 아니라 오류가 발생한 위치가 응답 형식을 결정한다는 점이다.

시사점: 화면 라우트를 $fetch로 호출해 JSON 오류 본문을 읽는 관행은 향후 취약해질 수 있다. 구조화된 오류 계약이 필요한 요청은 server route로 옮기고, 인증 실패를 오류 페이지로 보여줘야 하는 경우에는 route middleware 경계를 확인한다. 캐시/CDN에서는 동일 URL이 헤더마다 다른 표현을 갖는지에 대한 Vary 의존도도 함께 점검한다.

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

런타임: CI·개발 컨테이너·배포 플랫폼의 Node 버전을 수집하고, H3 v2 검증용 job은 Node 20.19 이상으로 고정한다.
서버 계약: 대표 페이지 오류, server API 오류, server middleware 인증 오류를 각각 요청해 content-type·상태 코드·오류 본문을 스냅샷 테스트로 남긴다.
프록시: devProxy를 쓰면 일반 HTTP, ws: true 경로, 와일드카드 경로, HMR을 한 시나리오에서 점검한다. main 커밋을 운영 의존성으로 올리지는 않는다.
빌드 확장: 프로젝트의 Vite 플러그인을 목록화해 클라이언트 전용/서버 번들 공통/빌드 도구 종속으로 분류한다. 공통화 후보는 resolveId·load·transform에 한정한다.
업그레이드 운영: lockfile 변경 PR에는 Node 버전, 서버 오류 contract, SSR 렌더, WebSocket smoke test 결과를 함께 첨부한다.

자주 묻는 질문 (FAQ)

Q. 이번 주에 Nuxt를 H3 v2로 올려야 하나요?

A. 아니다. H3 v2.0.1은 정식 릴리즈지만, 이 기간에 확인한 Nitro와 Nuxt 변경은 main 브랜치 작업이다. Nuxt/Nitro의 호환 릴리즈 노트와 프로젝트의 Node 조건을 확인한 뒤 별도 브랜치에서 검증하는 순서가 적절하다.

Q. Vite 또는 Vue의 새 안정 버전은 있었나요?

A. 이번 72시간 조사에서 Nuxt, Vue, Vite의 새 안정 릴리즈는 확인하지 못했다. 그래서 릴리즈가 없는 영역을 억지로 채우지 않고, Nuxt 서버·Nitro 빌드 계층에 실제로 누적된 공개 main 변경과 H3의 정식 릴리즈만 구분해 다뤘다.

Q. 가장 먼저 자동화할 테스트는 무엇인가요?

A. Node 버전 확인, 세 종류의 오류 응답 검증, WebSocket 프록시/HMR 공존 smoke test다. 이 세 가지는 런타임·응답 계약·개발 경험의 경계에서 발생할 회귀를 빠르게 잡는다.

출처와 관찰 범위

관찰 창은 KST 2026-10-02 09:00부터 2026-10-05 09:00까지다. H3 항목은 정식 릴리즈이며, 나머지 Nuxt/Nitro 항목은 GitHub main 브랜치 커밋으로 미출시 상태다. 릴리즈와 개발 브랜치의 상태를 혼동하지 않는 것이 이번 리포트의 핵심 운영 원칙이다.

더 깊게 읽기: 실전 가이드

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