Release·  

Nuxt 4.3

Nuxt 4.3 已发布 – 路由规则布局、ISR 负载提取、可拖拽错误覆盖层等新特性！
Daniel Roe

Daniel Roe

@danielroe.dev

Nuxt 4.3 带来了强大的布局、缓存和开发者体验新功能 —— 以及显著的性能提升。

📣 一些更新

延长 v3 支持

本月初，我发起了一个讨论了解从 v3 升级到 v4 的情况。很高兴听到大多数用户升级顺利。

话虽如此，我们承诺不让任何人被落下。因此，我们将继续提供安全更新和关键 bug 修复，超出此前宣布的 2026 年 1 月 31 日的生命周期结束日期，Nuxt v3 的生命周期将延续至 2026 年 7 月 31 日。

和往常一样，今天也发布了 v3 的一个小版本，包含了很多从 v4.3 回移植的改进。

为 Nuxt 5 做准备

我们离 Nuxt v5 和 Nitro v3 的发布比以往更近了。接下来几周，Nuxt 仓库的 main 分支将开始接收 Nuxt 5 的初始提交。但目前一切依旧照常进行。

  • 继续向 main 分支提交 pull request
  • 我们会将变更回移植到 4.x 和 3.x 分支

请关注升级指南 —— 我们将添加如何开始将项目迁移并为 Nuxt v5 做好准备（即设置 future.compatibilityVersion: 5）的详情。

🗂️ 路由规则布局

说完未来的事情，今天我们也带来许多好消息！

首先，现在可以通过新属性 appLayout 直接在路由规则中设置布局（#31092）。这提供了一种集中式的声明式方式来管理应用程序中的布局，无需在各页面中分散调用 definePageMeta。

nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/admin/**': { appLayout: 'admin' },
    '/dashboard/**': { appLayout: 'dashboard' },
    '/auth/**': { appLayout: 'minimal' }
  }
})

这在以下场景中非常有用：

  • 多个路由共享同一布局的管理面板
  • 需要与应用主布局不同的营销页面
此外，你现在可以向布局传递 props！详见下方使用 setPageLayout 传递布局 props。

📦 ISR/SWR 负载提取

负载提取现在支持 ISR（增量静态再生成）、SWR（过期-再验证）和缓存的 routeRules（#33467）。此前只有预渲染页面能生成 _payload.json 文件。

这意味着：

  • 客户端导航到 ISR/SWR 页面可以使用缓存的负载
  • CDN（如 Vercel、Netlify、Cloudflare）可缓存负载文件与 HTML 文件一起
  • 导航时减少 API 调用 —— 数据可预取并从缓存负载中服务
nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/products/**': { 
      isr: 3600, // 每小时重新验证
    }
  }
})

🧹 开发模式负载提取

相关地，开发模式下也支持负载提取（#30784），这让测试和调试负载行为变得更容易，无需生产构建。

负载提取在开发模式下需 nitro.static 设为 true，或者针对具体开启了 isr、swr、prerender 或 cache 路由规则的页面生效。

🚫 从 Layers 中禁用模块

扩展 Nuxt 层时，现在可以禁用不需要的特定模块（#33883）。只需将模块配置设置为 false：

nuxt.config.ts
export default defineNuxtConfig({
  extends: ['../shared-layer'],
  // 禁用来自层的 @nuxt/image
  image: false,
})

🏷️ 页面元信息中的路由组

路由组（用括号包裹的文件夹，如 (protected)/）现在会暴露在页面元信息中（#33460）。这使得你在中间件或任何能访问路由的位置轻松检测路由所属组。

pages/(protected)/dashboard.vue
<script setup lang="ts">
// 该页面的元信息将包含: { groups: ['protected'] }
useRoute().meta.groups
</script>
middleware/auth.ts
export default defineNuxtRouteMiddleware((to) => {
  if (to.meta.groups?.includes('protected') && !isAuthenticated()) {
    return navigateTo('/login')
  }
})

这为基于约定的路由级授权提供了清晰的解决方案，无需在每个受保护页面添加 definePageMeta。

🎨 使用 setPageLayout 传递布局 Props

setPageLayout 组合函数现在支持第二个参数，可向布局传递 props（#33805）：

middleware/admin.ts
export default defineNuxtRouteMiddleware((to) => {
  setPageLayout('admin', {
    sidebar: true,
    theme: 'dark'
  })
})
layouts/admin.vue
<script setup lang="ts">
defineProps<{
  sidebar?: boolean
  theme?: 'light' | 'dark'
}>()
</script>

🔧 #server 别名

新增 #server 别名，方便在服务器目录中进行干净导入（#33870），类似于 #shared：

server/api/users/[id]/profile.ts
// 之前：相对路径地狱
import { helper } from '../../../../utils/helper'

// 现在：清晰且可预测
import { helper } from '#server/utils/helper'

该别名具备导入保护 —— 不能误从客户端或共享上下文导入 #server 代码。

🪟 可拖拽错误覆盖层

Nuxt 4.2 引入的开发错误覆盖层现在支持拖拽和最小化功能（#33695）。你可以：

  • 拖拽到屏幕任意角落（自动吸附边缘）
  • 最小化成一个小按钮，在继续工作时保持视野
  • 位置和最小化状态在页面刷新后保持

这大幅提升调试体验，避免覆盖层阻挡视线。

⚙️ 异步插件构造函数

模块开发者现在可以使用异步函数添加构建插件（#33619）：

modules/my-module.ts
export default defineNuxtModule({
  async setup() {
    // 仅在需要时懒加载
    addVitePlugin(() => import('my-cool-plugin').then(r => r.default()))
    
    // 使用 Vite 时无需加载 webpack 插件
    addWebpackPlugin(() => import('my-cool-plugin/webpack').then(r => r.default()))
  }
})

这实现了构建插件的真正懒加载，避免了不必要的代码加载。

🚀 性能提升

本次发布包含多项性能优化，加速构建：

  • Hook 过滤 —— 内部插件使用过滤器避免不必要执行钩子（#33898）
  • SSR 样式优化 —— nuxt:ssr-styles 插件显著加快（#33862，#33865）
  • Layer 别名转换 —— Vite 环境跳过（其原生处理）（#33864）
  • 路由规则编译 —— 使用 rou3 编译成客户端代码块，移除客户端包中的 radix3，消除应用清单请求（#33920）

🎨 Webpack/Rspack 支持内联样式

inlineStyles 功能现在支持 webpack 和 rspack 构建器（#33966），不仅限于 Vite。无论打包工具如何，都可实现关键 CSS 内联，提升核心网络指标。

⚠️ 弃用提示

statusCode → status，statusMessage → statusText

为适配 Nitro v3 和 H3 v2，正在迁移至 Web API 命名规范（#33912）。旧属性依然有效但在 v5 之前已被弃用：

- throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+ throw createError({ status: 404, statusText: 'Not Found' })

🐛 Bug 修复

本次修复的重点包括：

  • 修复使用 key 属性时 head 组件去重问题（#33958，#33963）
  • 修复 Options API 中异步数据属性不具备响应性的问题（#34119）
  • 修复 useCookie 解码时数字解析不安全的问题（#34007）
  • 修复当嵌套的 NuxtLayout 禁用布局时 NuxtPage 未重新渲染的问题（#34078）
  • 修复客户端路径名对非 ASCII 路由别名的解码（#34043）
  • 修复挂起状态导航后 suspense 再挂载的问题（#33991）
  • 修复错误覆盖层里的剪贴板复制功能（#33873）
  • 默认开启 TypeScript 配置中的 allowArbitraryExtensions（#34084）
  • 为服务器 tsconfig 新增 noUncheckedIndexedAccess 以更安全的类型检查（#33985）
在 Nitro 服务器端 TypeScript 配置中启用 noUncheckedIndexedAccess 提升类型安全，但可能暴露你服务器代码中的类型错误。该改动是因为 Nuxt 的应用上下文会对服务器路由做类型检查（了解更多）。我们建议保持开启以获得更安全的类型检测，但可根据需要禁用：
nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    typescript: {
      tsConfig: {
        compilerOptions: {
          noUncheckedIndexedAccess: false
        }
      }
    }
  }
})
注意，禁用可能导致类型错误未被发现，进而产生运行时索引访问问题。

📚 文档

  • 改进模块作者指南结构更清晰（#33803）
  • 添加 Claude Desktop 的 MCP 配置说明（#33914）
  • 新增层目录文档（#33967）
  • 新增 Deno 包管理器示例（#34070）
  • 详细说明服务器路由的类型检查上下文限制（#33964）

🎉 Nuxt 3.21.0

与 v4.3.0 一同发布的还有Nuxt v3.21.0，它包含了许多相同改进回移至 3.x 分支。本次发布包括：

  • 所有同样的功能：路由规则布局、ISR 负载提取、使用 setPageLayout 传递布局 props、#server 别名、可拖拽错误覆盖层等
  • 所有性能提升：SSR 样式优化、hook 过滤、路由规则编译
  • 模块禁用功能：通过将配置设为 false 禁用层模块
  • 关键 bug 修复：Options API 中异步数据响应性、useCookie 数字解析、head 组件去重等

✅ 升级指南

升级建议运行：

npx nuxt upgrade --dedupe

# 或者如果升级至 v3.21
npx nuxt@latest upgrade --dedupe --channel=v3

这将去重你的锁文件，并确保拉取 Nuxt 依赖及其生态中 unjs 库的更新。

如果从旧版本升级，请参考我们的升级指南。

👉 完整发布说明

查看 Nuxt v4.3.0 的完整发布说明。
查看 Nuxt v3.21.0 的完整发布说明。

感谢所有为本次发布贡献的开发者们！💚

← 返回博客
Nuxt on LinkedInNuxt on BlueskyNuxt on X