Nuxt v4.6.0 发布：迈向服务端无关化

译注：本文编译自 Nuxt 官方 GitHub Release Notes，原文链接见文末。发布日期为 2026-10-05。

Nuxt v4.6.0 是一个 minor 版本，但官方称其为「最大的 minor 版本之一」——自 v4.5.2 以来包含超过 420 个 commit。本次发布的核心是让 Nuxt 走向服务端无关（server-agnostic），同时带来全新的 Nuxt CLI v4、应用级密钥与 Session、重建的类型化 $fetch，以及大量性能优化。

Nuxt CLI v4

与 Nuxt v4.6 同步发布的还有 @nuxt/cli v4。它作为 nuxt 的依赖自动安装，升级即可获得。主要变化集中在 nuxt dev：

• 交互式终端 UI，展示 URL、启动进度与快捷键，并可进入错误日志、路由、网络请求等面板
• 开发服务器提供更多信息：为何重载或重启、哪些 nuxt.config 键发生变化、慢启动或构建的时间去向、各模块初始化耗时
• CLI 级错误通道，由 my-bad 渲染，可在修复 nuxt.config.ts 语法错误后自动重载页面
• .nuxt/ 下的锁文件，允许第二个 nuxt dev（例如由 agent 启动）接管或让位，并支撑新的 nuxt curl 与 nuxt task 命令

此外还有 nuxt docs "<query>" 搜索，以及 nuxt preview --takeover 可替换正在运行的预览服务器。体积与启动速度改善明显：

指标	v3.37	v4.0	变化
@nuxt/cli 安装体积	13.1 MB	3.5 MB	-73%
@nuxt/cli 依赖数	70	31	-56%
nuxt dev 首次绘制	330 ms	50 ms	快 6.6 倍
nuxt dev 端口绑定	338 ms	104 ms	快 3.2 倍
nuxt dev 静息内存（Linux）	630 MB	440 MB	-30%

虽然是 major 版本，但对 Nuxt v4 用户不应构成破坏性变更：要求 Node.js v22.21+、v24.11+ 或 v26+，移除 nuxt init（仅支持 npm create nuxt@latest），并停止支持 Nuxt 2 与 @nuxt/bridge。

服务端无关化与 nuxt/server

此前 #app 组合式函数导入 h3 类型，服务端代码从 h3、nitropack 导入，任何触及服务端的模块都被绑定到 Nuxt 恰好依赖的那些包的 major 版本上。本次发布改变了这一点：Nuxt 在 nuxt/kit 中显式定义公共 API，自行定义请求事件、路由规则与类型化 $fetch 的类型，并暴露 nuxt/server 作为服务端工具导入面。

import { defineEventHandler, getQuery } from 'nuxt/server'

export default defineEventHandler((event) => {
  const { name } = getQuery<{ name?: string }>(event)
  return { message: `Hello, ${name ?? 'world'}!` }
})

工具基于 Web 标准，并针对可移植的 RequestEvent 类型化：event.req（Request）、event.url（URL）、event.res（status/statusText/headers）、event.context（每请求上下文）。底层由 @nuxt/nitro-server 通过 Nitro 与 h3 支撑，但用户无需从二者导入。官方同时宣布了实验性实现 @nuxt/vite-server，允许使用 Vite Environment API 进行纯 Vite 服务端构建。

官方强调 Nitro 仍是绝大多数场景的正确选择。nuxt/server 的主要收益包括：平滑升级到 Nuxt 5（迁移至 Nitro v3 与 h3 v2）、将 Nuxt 与 Nitro 发布周期解耦、提升代码可维护性。

需要注意：在 Nuxt 4 上，自动导入的 defineEventHandler、getQuery、readBody 等仍是 h3 自身的 helper，事件形态不同。若混用会看到 NUXT_E8012 错误。部分 helper 行为也与 h3 v1 同名函数不同，例如 sendRedirect 返回响应而非直接发送，createError 接受 status 与 statusText。本次发布不强制迁移。

appSecret 与 Session

Nuxt 新增根应用密钥 runtimeConfig.appSecret，通过 NUXT_APP_SECRET 设置。模块与服务端特性可用 deriveSecret(purpose) 从中派生特定用途的密钥，因此只需配置这一个密钥：

openssl rand -base64 32

开发环境下若未配置，Nuxt 会生成并持久化一个（首次使用派生密钥时给出警告）；构建过程永不生成。首个使用者是 nuxt/server 中的 Session helper，Session 通过 iron 密封进 cookie，无需配置服务端存储：

import { defineEventHandler, useSession } from 'nuxt/server'

export default defineEventHandler(async (event) => {
  const session = await useSession<{ visits: number }>(event)
  await session.update(data => ({ visits: (data.visits ?? 0) + 1 }))
  return { visits: session.data.visits }
})

以 app 为前缀的 runtime config 键（runtimeConfig.app、runtimeConfig.appSecret）为 Nuxt 保留。

重建的类型化 $fetch

旧的类型化 $fetch 派生自 Nitro 的 InternalApi 接口，路由数超过几百条后会触发 TS2589: Type instantiation is excessively deep and possibly infinite。新版基于 fetchdts 重建，将服务端路由编译为路由树，静态路径使用精确匹配表，解析成本随调用点而非路由数增长：

路由数	之前	之后
100	1,397,361 次实例化 / 0.77s	51,558 / 0.26s
300	5,774,425 / 3.49s（TS2589）	51,558 / 0.16s
1000	12,831,467 / 7.44s（TS2589）	51,558 / 0.20s
3000（200 调用点）	71,875,148 / 53.63s（TS2589）	101,678 / 0.62s

相同运行的峰值内存从 946 MB 降至 140 MB。路由集还会携带 handler 校验的 body、query 与 headers，使调用检查更严格。该特性在 Nuxt 4 上需通过 experimental.routeTypedFetch: true 开启，Nuxt 5 中为默认。另有 experimental.strictRouteTypes 与 'isomorphic' 模式。

开发体验与性能

• my-bad 错误展示：开发环境 SSR 堆栈现在会在读取错误前完成映射，Youch 覆盖层被 my-bad 取代，渲染进应用自身的错误页并附带源码 code frame，终端同步打印。
• 新加载屏与 404/错误页：加载屏改为 WebGL2 粒子场，无 WebGL2 时回退静态图形，prefers-reduced-motion 下停止动画；404 与错误页采用中性配色，404 页新增返回按钮。
• Vue Vapor 支持：以 interop 模式支持 Vue 3.6 的 Vapor Mode，应用根仍使用虚拟 DOM，可在 <script setup> 上加 vapor 属性按组件或页面启用，需 Vue ^3.6.0-rc.2 或更新版本。
• useFetch/useAsyncData addons：createUseFetch 与 createUseAsyncData 工厂新增 addons 选项，可声明自定义调用参数、调整合并选项、以中间件包裹 handler 并扩展返回值。
• 性能优化：<NuxtLink> 服务端渲染快 58%；experimental.early404 下 30 页应用的 JSON 404 从 37.1ms 降至 0.3ms；模板声明依赖后编辑组件不再重生成全部 49 个核心模板；useCookie 每请求只解析一次 cookie 头；ssr: false 页面从服务端 bundle 中 tree-shake。

综合基准（arm64 Linux，Node 24.15，5 次运行中位数）：

指标	v4.5.2	v4.6.0	变化
@nuxt/kit 安装体积	6.4 MB	2.1 MB	-67%
@nuxt/kit 传递依赖	36	22	-39%
nuxt build（starter）	4.4 s	3.6 s	-18%
nuxt build（200 页/200 组件/50 路由）	11.6 s	10.3 s	-11%
SSR 吞吐（含 300 个 <NuxtLink> 的页面）	110 req/s	140 req/s	+26%

更轻的载荷

useAsyncData 与 useFetch 接受 serialize: false，可将数据排除在 __NUXT_DATA__ 载荷之外，适用于永不 hydrate 的组件；experimental.stripNeverHydratedData 会对 hydrate-never 组件树内的数据自动应用。开发环境下，页面载荷超过 100 kB 会给出警告，使用 noScripts 渲染却依赖客户端 JavaScript 的路由也会警告。

升级提示

Nuxt 3 已于 2026 年 7 月 31 日结束生命周期，因此本次没有 3.x 版本同步发布。本次发布几乎全部特性已进入 Nuxt 5 分支，大部分 Nuxt 5 默认值可通过 future.compatibilityVersion: 5 提前测试。

原文链接

• https://github.com/nuxt/nuxt/releases/tag/v4.6.0