---
title: "Nuxt 4.3"
description: "Nuxt 4.3 发布了 – 路由规则布局、ISR 负载提取、可拖拽错误覆盖层，等等！"
canonical_url: "https://nuxt.zhcndoc.com/blog/v4-3"
---
# Nuxt 4.3

> Nuxt 4.3 发布了 – 路由规则布局、ISR 负载提取、可拖拽错误覆盖层，等等！

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

## 📣 一些更新

### 延长 v3 支持

本月初，我[发起了一个讨论](https://github.com/nuxt/nuxt/discussions/33918)了解从 v3 升级到 v4 的情况。很高兴听到大多数用户升级顺利。

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

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

### 为 Nuxt 5 做准备

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

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

请关注[升级指南](https://nuxt.zhcndoc.com/docs/4.x/getting-started/upgrade) —— 我们将添加如何开始将项目迁移并为 Nuxt v5 做好准备（即设置 `future.compatibilityVersion: 5`）的详情。

## 🗂️ 路由规则布局

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

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

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

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

- 多个路由共享同一布局的管理面板
- 需要与应用主布局不同的营销页面

::tip
此外，你现在可以向布局传递 props！详见下方[使用 `setPageLayout` 传递布局 props](#layout-props-with-setpagelayout)。
::

## 📦 ISR/SWR 负载提取

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

这意味着：

- 客户端导航到 ISR/SWR 页面可以使用缓存的负载
- CDN（如 Vercel、Netlify、Cloudflare）可缓存负载文件与 HTML 文件一起
- 导航时减少 API 调用 —— 数据可预取并从缓存负载中服务

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  routeRules: {
    '/products/**': { 
      isr: 3600, // 每小时重新验证
    }
  }
})
```

## 🧹 开发模式负载提取

相关地，开发模式下也支持负载提取（[#30784](https://github.com/nuxt/nuxt/pull/30784)），这让测试和调试负载行为变得更容易，无需生产构建。

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

## 🚫 从 Layers 中禁用模块

扩展 Nuxt 层时，现在可以禁用不需要的特定模块（[#33883](https://github.com/nuxt/nuxt/pull/33883)）。只需将模块配置设置为 `false`：

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

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

[路由组](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages#route-groups)（用括号包裹的文件夹，如 `(protected)/`）现在会暴露在页面元信息中（[#33460](https://github.com/nuxt/nuxt/pull/33460)）。这使得你在中间件或任何能访问路由的位置轻松检测路由所属组。

```vue [pages/(protected)/dashboard.vue]
<script setup lang="ts">
// 该页面的元信息将包含: { groups: ['protected'] }
useRoute().meta.groups
</script>
```

```ts [middleware/auth.ts]
export default defineNuxtRouteMiddleware((to) => {
  if (to.meta.groups?.includes('protected') && !isAuthenticated()) {
    return navigateTo('/login')
  }
})
```

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

## 🎨 使用 `setPageLayout` 传递布局 Props

`setPageLayout` 组合函数现在支持第二个参数，可向布局传递 props（[#33805](https://github.com/nuxt/nuxt/pull/33805)）：

```ts [middleware/admin.ts]
export default defineNuxtRouteMiddleware((to) => {
  setPageLayout('admin', {
    sidebar: true,
    theme: 'dark'
  })
})
```

```vue [layouts/admin.vue]
<script setup lang="ts">
defineProps<{
  sidebar?: boolean
  theme?: 'light' | 'dark'
}>()
</script>
```

## 🔧 `#server` 别名

新增 `#server` 别名，方便在服务器目录中进行干净导入（[#33870](https://github.com/nuxt/nuxt/pull/33870)），类似于 `#shared`：

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

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

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

## 🪟 可拖拽错误覆盖层

Nuxt 4.2 引入的开发错误覆盖层现在支持拖拽和最小化功能（[#33695](https://github.com/nuxt/nuxt/pull/33695)）。你可以：

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

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

::video{poster="https://res.cloudinary.com/dchoja2nb/video/upload/v1769103044/nuxt_4-3_error_caqkhk.jpg" controls .rounded.dark:border.dark:border-gray-700}
  :::source{src="https://res.cloudinary.com/dchoja2nb/video/upload/v1769103044/nuxt_4-3_error_caqkhk.webm" type="video/webm"}
  :::

  :::source{src="https://res.cloudinary.com/dchoja2nb/video/upload/v1769103044/nuxt_4-3_error_caqkhk.mp4" type="video/mp4"}
  :::

  :::source{src="https://res.cloudinary.com/dchoja2nb/video/upload/v1769103044/nuxt_4-3_error_caqkhk.ogg" type="video/ogg"}
  :::
::

## ⚙️ 异步插件构造函数

模块开发者现在可以使用异步函数添加构建插件（[#33619](https://github.com/nuxt/nuxt/pull/33619)）：

```ts [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](https://github.com/nuxt/nuxt/pull/33898)）
- **SSR 样式优化** —— `nuxt:ssr-styles` 插件显著加快（[#33862](https://github.com/nuxt/nuxt/pull/33862)，[#33865](https://github.com/nuxt/nuxt/pull/33865)）
- **Layer 别名转换** —— Vite 环境跳过（其原生处理）（[#33864](https://github.com/nuxt/nuxt/pull/33864)）
- **路由规则编译** —— 使用 `rou3` 编译成客户端代码块，移除客户端包中的 `radix3`，消除应用清单请求（[#33920](https://github.com/nuxt/nuxt/pull/33920)）

## 🎨 Webpack/Rspack 支持内联样式

`inlineStyles` 功能现在支持 webpack 和 rspack 构建器（[#33966](https://github.com/nuxt/nuxt/pull/33966)），不仅限于 Vite。无论打包工具如何，都可实现关键 CSS 内联，提升核心网络指标。

## ⚠️ 弃用提示

### `statusCode` → `status`，`statusMessage` → `statusText`

为适配 Nitro v3 和 H3 v2，正在迁移至 Web API 命名规范（[#33912](https://github.com/nuxt/nuxt/pull/33912)）。旧属性依然有效但在 v5 之前已被弃用：

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

## 🐛 Bug 修复

本次修复的重点包括：

- 修复使用 `key` 属性时 head 组件去重问题（[#33958](https://github.com/nuxt/nuxt/pull/33958)，[#33963](https://github.com/nuxt/nuxt/pull/33963)）
- 修复 Options API 中异步数据属性不具备响应性的问题（[#34119](https://github.com/nuxt/nuxt/pull/34119)）
- 修复 `useCookie` 解码时数字解析不安全的问题（[#34007](https://github.com/nuxt/nuxt/pull/34007)）
- 修复当嵌套的 `NuxtLayout` 禁用布局时 `NuxtPage` 未重新渲染的问题（[#34078](https://github.com/nuxt/nuxt/pull/34078)）
- 修复客户端路径名对非 ASCII 路由别名的解码（[#34043](https://github.com/nuxt/nuxt/pull/34043)）
- 修复挂起状态导航后 suspense 再挂载的问题（[#33991](https://github.com/nuxt/nuxt/pull/33991)）
- 修复错误覆盖层里的剪贴板复制功能（[#33873](https://github.com/nuxt/nuxt/pull/33873)）
- 默认开启 TypeScript 配置中的 `allowArbitraryExtensions`（[#34084](https://github.com/nuxt/nuxt/pull/34084)）
- 为服务器 tsconfig 新增 `noUncheckedIndexedAccess` 以更安全的类型检查（[#33985](https://github.com/nuxt/nuxt/pull/33985)）

::important
在 Nitro 服务器端 TypeScript 配置中启用 `noUncheckedIndexedAccess` 提升类型安全，但可能暴露你服务器代码中的类型错误。该改动是因为 Nuxt 的应用上下文会对服务器路由做类型检查（[了解更多](https://nuxt.com/docs/4.x/guide/modules/recipes-advanced#known-limitations)）。

我们建议保持开启以获得更安全的类型检测，但可根据需要禁用：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    typescript: {
      tsConfig: {
        compilerOptions: {
          noUncheckedIndexedAccess: false
        }
      }
    }
  }
})
```

注意，禁用可能导致类型错误未被发现，进而产生运行时索引访问问题。
::

## 📚 文档

- 改进模块作者指南结构更清晰（[#33803](https://github.com/nuxt/nuxt/pull/33803)）
- 添加 Claude Desktop 的 MCP 配置说明（[#33914](https://github.com/nuxt/nuxt/pull/33914)）
- 新增层目录文档（[#33967](https://github.com/nuxt/nuxt/pull/33967)）
- 新增 Deno 包管理器示例（[#34070](https://github.com/nuxt/nuxt/pull/34070)）
- 详细说明服务器路由的类型检查上下文限制（[#33964](https://github.com/nuxt/nuxt/pull/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 组件去重等

## ✅ 升级指南

升级建议运行：

```sh
npx nuxt upgrade --dedupe

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

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

::tip
如果从旧版本升级，请参考我们的[升级指南](https://nuxt.zhcndoc.com/docs/getting-started/upgrade)。
::

## 👉 完整发布说明

::read-more{icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v4.3.0"}
查看 Nuxt `v4.3.0` 的完整发布说明。
::

::read-more{icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.21.0"}
查看 Nuxt `v3.21.0` 的完整发布说明。
::

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


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.