Nuxt 4.2

我们很高兴地宣布 Nuxt 4.2 发布了，带来了更好的 TypeScript 开发体验、更强的错误处理能力，以及对数据获取更精细的控制！🎉

🎯 数据获取的中止控制

现在你可以直接在 useAsyncData 中使用 AbortController 信号，使你能够精细地控制请求取消 (#32531)。

这是通过向你的 useAsyncData handler 传入内部信号实现的，可以取消任何可取消的 Promise，比如 $fetch。

<script setup lang="ts">
const { data, error, clear, refresh } = await useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', {
  signal
}))

refresh() // 在 dedupe: cancel 模式下，会真正取消 $fetch 请求
  
clear() // 取消最近的挂起 handler
</script>

你同样可以直接将 AbortController 信号传递给 refresh/execute，让你能够精细地控制请求取消。这在你需要基于用户操作或组件生命周期事件中止请求时特别有用。

const { data, refresh } = await useAsyncData('posts', fetchPosts)

// 取消正在进行的刷新请求
const abortController = new AbortController()
refresh({ signal: abortController.signal })

// 稍后...
abortController.abort()

🎨 开发阶段更好的错误页面

当开发阶段发生错误时，Nuxt 现在将同时显示你的自定义错误页和详细的技术错误覆盖层 (#33359)。这样你既能看到用户真实会体验到的错误页面，又可以立即访问堆栈跟踪和调试信息。

技术覆盖层作为可切换面板出现，不会干扰你的自定义错误页面，使调试问题变得更容易，同时保持错误处理的真实预览。

🔮 可选开启的 Vite 环境 API

对于想试验前沿特性的用户，现在可以自主选择开启 Vite Environment API (#33492)。

Vite Environment API 是 Vite 6 的一项重大架构改进。它弥合了开发和生产之间的差距，允许 Vite 开发服务器并发处理多个环境（而不是像以前 Nuxt 中那样需要多个 Vite 开发服务器）。

这应当能提升开发性能并消除一些边缘用例下的 bug。

…并且这是实现 Nitro 作为 Vite 环境的基础，这将进一步加速开发服务器，同时也可让开发环境与你的 Nitro 预设保持更一致。

export default defineNuxtConfig({
  experimental: {
    viteEnvironmentApi: true
  }
})

这也是 Nuxt v5 的第一个破坏性变更特性。你可以通过设置 compatibilityVersion 到 5 来选择开启这些破坏性变更：

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 5
  },
})

请仅用于测试，因为这会选择启用无限的未来破坏性变更，包括我们发布 Nuxt 集成后升级到 Nitro v3。

📦 新的 @nuxt/nitro-server 包

我们已将 Nitro 服务器集成拆分为独立包：@nuxt/nitro-server (#33462)。这一架构变更支持不同的 Nitro 集成模式，并为服务器端渲染未来的创新铺平了道路。

虽然这次变更主要是内部调整，但它是我们持续努力让 Nuxt 更加模块化和灵活的一部分。新包提供了独立的 Nitro 集成，并为未来的替代集成方式（比如在 Nuxt v5+ 使用 Nitro 作为 Vite 插件）打下了基础。

⚡ 性能提升

我们还带来了若干性能优化：

• 预计算渲染器依赖 —— 现在我们在构建时计算渲染器依赖，而非运行时，提升冷启动和首屏渲染性能 (#33361)
• 减少依赖 —— 移除了 kit 和 schema 包中的不必要依赖 (7ae2cf563)

📉 异步数据处理函数提取

最令人兴奋的性能改进之一是新的实验性异步数据处理函数提取功能 (#33131)。启用后，传给 useAsyncData 和 useLazyAsyncData 的 handler 函数会被自动提取成独立的代码块并动态导入。

这对预渲染的静态站点尤其有效，因为数据获取逻辑仅在构建时需要，可以完全从客户端包中剔除。

<script setup lang="ts">
// 此 handler 会被提取为独立代码块
// 仅在需要时加载
const { data: post } = await useAsyncData('post', async () => {
  const content = await queryContent(`/blog/${route.params.slug}`).findOne()
  
  // 复杂的数据处理逻辑，不希望打包进客户端
  const processed = await processMarkdown(content)
  const related = await findRelatedPosts(content.tags)
  
  return {
    ...processed,
    related
  }
})
</script>

对于静态/预渲染站点，可以在配置中启用：

export default defineNuxtConfig({
  experimental: {
    extractAsyncDataHandlers: true
  }
})

提取出的处理函数会在预渲染时从客户端包中进行 tree-shake，因为数据已在负载中可用。这显著减小了交付给用户的 JavaScript 文件大小。

🔧 实验性的 TypeScript 插件支持

我们引入了通过 @dxup/nuxt 模块，提升 TypeScript 开发体验的实验性支持。

该模块提供多个 TypeScript 插件，旨在改善你使用 Nuxt 特性时的体验：

• 智能组件重命名：重命名自动导入的组件文件时，自动更新所有引用
• 动态导入定位：使用诸如import(`~/assets/${name}.webp`)这类 glob 模式时，可以直接跳转到文件
• Nitro 路由导航：从数据获取函数（$fetch，useFetch，useLazyFetch）跳转到服务端路由处理器
• 运行时配置导航：运行时配置属性支持无缝跳转到定义
• 增强自动导入支持：包含 @dxup/unimport 插件，提升自动导入的组合式函数和工具的导航能力

要启用此功能，在 Nuxt 配置中设置 experimental.typescriptPlugin 为 true：

export default defineNuxtConfig({
  experimental: {
    typescriptPlugin: true
  }
})

启用后，模块将由 Nuxt 自动安装和配置。

🎁 其他改进

• 组件的 declarationPath —— 现在可以为组件指定自定义声明路径 (#33419)
• 模块解析扩展名 —— Kit 的 resolveModule 现支持 extensions 选项 (#33328)
• 全局 head 工具 —— Kit 新增 setGlobalHead 工具，方便进行页面头部管理 (#33512)

🩹 重要修复

• 基于 routeRules 重定向时保留路由 hash (#33222)
• 并发调用 loadNuxtConfig 时正确清理 (#33420)
• <NuxtLink> 中对象格式 href 正确工作 (c69e4c30d)
• 组件自动导入现在可作为 Vue 的 h() 函数参数使用 (#33509)
• 修复 HMR 期间应用配置的数组处理 (#33555)

✅ 升级指南

我们推荐通过运行以下命令完成升级：

npx nuxt upgrade --dedupe

这将刷新锁文件，并拉取 Nuxt 依赖的最新包，特别是 unjs 生态相关的依赖。

👉 完整发行说明

感谢你读到这里！希望你喜欢本次发布，如有任何反馈或问题，欢迎随时告诉我们。

祝你 Nuxt 快乐 ✨