nuxt

이것은 Nuxt 4.6.0에서 발생한 TypeScript 제네릭 추론 회귀입니다. useFetch<{ items: number[] }>()와 같이 명시적인 응답 타입을 제공하면 BaseURL 제네릭이 리터럴 타입 ''으로 기본 설정되어, useRuntimeConfig()에서 가져온 런타임 string이 거부됩니다.

해결 방법 1 — 기본 URL로 fetch 인스턴스를 생성하고 $fetch를 통해 전달합니다:

const config = useRuntimeConfig()
const api = $fetch.create({ baseURL: config.public.apiBase })

useFetch<{ items: number[] }>('/x', { $fetch: api })
useLazyFetch<{ items: number[] }>('/x', { $fetch: api })

해결 방법 2 — 전체 URL을 구성하고 baseURL을 생략합니다:

const config = useRuntimeConfig()
useFetch<{ items: number[] }>(`${config.public.apiBase}/x`)

동일한 해결 방법이 #build/fetch에서 가져온 $fetch에도 적용됩니다. 임시 조치로, 이전 동작이 정상 작동했던 Nuxt 4.5.2로 다운그레이드할 수도 있습니다.

이것은 Nuxt 4.6.0의 SerializeObject에 존재하는 타입 레벨 버그입니다. 이 타입은 Omit<T, FilterKeys<T, NonJsonPrimitive>>를 사용하는데, T에 인덱스 시그니처가 있으면 keyof T가 string | number가 되어 매핑된 타입 처리 과정에서 명명된 키들이 제거됩니다. node_modules/nuxt/dist/app/types/serialize.d.ts의 SerializeObject를 다음과 같은 키 리매핑 매핑 타입으로 교체하세요:

type SerializeObject<T extends object> = {
  [K in keyof T as T[K] extends NonJsonPrimitive ? never : K]: Serialize<T[K]>
}

이렇게 하면 docFormat과 name 같은 명명된 프로퍼티와 인덱스 시그니처가 모두 유지됩니다. patch-package로 변경 사항을 영구 적용하세요:

npx patch-package nuxt

그런 다음 postinstall에 patch-package를 추가하세요:

{ "scripts": { "postinstall": "patch-package" } }

Nuxt를 패치하지 않고 임시로 해결하려면, 응답을 명시적으로 수정된 타입으로 캐스팅하세요:

type SerializeObjectFixed<T extends object> = {
  [K in keyof T as T[K] extends NonJsonPrimitive ? never : K]: Serialize<T[K]>
}

const wire = JSON.parse(JSON.stringify(doc)) as SerializeObjectFixed<Doc>

같은 문제는 Zod의 .catchall(), z.looseObject(), .passthrough() 타입에서도 흔히 나타납니다. 연결된 수정 사항이 릴리스되면 Nuxt를 업그레이드하고, 그 전까지는 패치를 사용하세요.

Nuxt 4.6.1에서는 @nuxt/kit가 defu를 사용해 여러분의 typescript.appTsConfig(또는 tsConfig)를 생성된 tsconfig에 병합하며, 이로 인해 사용자 지정 include 항목이 ./nuxt.d.ts **앞에** 배치됩니다. 이렇게 포함된 파일 중 하나라도 nuxt/app을 import하면(예: 테스트 헬퍼), nitropack의 declare global { var $fetch: $Fetch }가 먼저 로드되므로, experimental.routeTypedFetch: true를 사용하더라도 전역 $fetch가 다시 $Fetch<unknown, NitroFetchRequest> 타입으로 지정됩니다. **우회 방법:** ./nuxt.d.ts를 include 배열의 첫 번째 항목으로 지정하세요:

export default defineNuxtConfig({
  experimental: { routeTypedFetch: true },
  typescript: {
    appTsConfig: {
      include: ['./nuxt.d.ts', '../test/**/*.ts'],
    },
  },
})

중복되는 ./nuxt.d.ts 항목은 Nuxt에 의해 중복 제거되며, 전역 $fetch는 다시 NuxtGlobalFetch로 타입이 지정됩니다. nuxi prepare를 실행한 다음 tsc -p .nuxt/tsconfig.app.json --noEmit으로 확인하세요.

extends 그래프에서 두 경로를 통해 도달하는 레이어는 경로마다 한 번씩 설정이 병합되어, 해당 레이어가 선언한 모든 배열이 두 배로 늘어납니다 — 예를 들어 nitro.cloudflare.wrangler.triggers.crons가 ['0 0 * * *','0 0 * * *']가 되고(Cloudflare 배포가 duplicate cron found ... [code: 10100] 오류로 실패함), nitro.scheduledTasks 작업 목록이 동시에 두 번씩 실행됩니다. 원인: @nuxt/kit의 seenLayerDirs 중복 제거 가드가 existsSync 검사 뒤에 위치하기 때문에, extends: ['@org/layer-a','@org/layer-b'] 같은 패키지 지정자는 중복 제거가 실행되기 전에 해당 검사를 통과하지 못합니다(nuxt 4.5.2 / c12 3.3.4에서 확인됨). 우회 방법: 패키지 이름 대신 상대 경로로 레이어를 지정하세요. 예: extends: ['./packages/a','./packages/b'] — 경로 형태로 지정하면 존재 검사를 통과하고 중복이 올바르게 제거됩니다. 아직 업스트림 수정은 배포되지 않았습니다.

이 문제는 Nuxt 4.6.2에서 발생한 Windows 전용 회귀 버그입니다(4.6.1에서는 정상 동작합니다). collectDevCss(@nuxt/vite-builder)에서 이제 module-graph URL이 toDevUrl()을 통과하게 되었고, 이 함수는 /로 시작하지 않는 모든 URL 앞에 /@id/를 붙입니다. Windows에서는 절대 경로가 드라이브 문자(예: D:/)로 시작하므로, SSR 스타일시트 링크가 /_nuxt/@id/D:/…/lib.css 형태가 됩니다. nuxt:dev-style-ssr 플러그인은 link[href="/_nuxt/<id>"]와 link[href="/_nuxt/@fs/<id>"]만 제거하기 때문에, /@id/ 링크는 하이드레이션 이후에도 제거되지 않습니다. 결과적으로 모든 전역 스타일시트(예: css: ['primeicons/primeicons.css'] 또는 모듈이 주입한 CSS)가 개발 환경에서 두 번 로드되고, 제거되지 않고 남은 링크가 Vite가 주입한 <style> 태그보다 앞에 위치하게 되어, @layer 우선순위가 더 이상 nuxt.options.css 순서를 따르지 않습니다(나중에 선언된 항목의 레이어가 가장 낮은 우선순위가 될 수 있습니다). 해결 방법: 패치가 릴리스될 때까지 Nuxt 4.6.1로 다운그레이드하거나 버전을 고정하세요(pnpm add nuxt@4.6.1 실행 또는 package.json에 override 추가). POSIX 시스템(Linux/macOS)은 절대 경로가 /로 시작하므로 영향을 받지 않습니다. 메인테이너를 위한 올바른 수정 방법: DevStyleSSRPlugin이 제거하는 셀렉터에 /@id/ 형태(joinURL(buildAssetsURL, '@id', moduleId))를 추가하거나, collectDevCss가 절대 경로에 대해 /@fs/ 형태를 출력하도록 수정하는 것입니다.