v4 路线图

We originally planned Nuxt 4 for June 2024, but things don't always go according to plan. I think it's appropriate to take a different approach:

👉 Nuxt 4 entered Release Candidate (RC) stage on July 8, 2025, with a stable release coming soon. Nuxt 5 will come later once Nitro v3 is ready.

Why Two Releases?

Honestly, in hindsight I think we should have shipped Nuxt v4 last year. It would have aligned better with our once-a-year plan for careful major releases.

On the other hand, it has allowed time for testing across countless projects, by opting in to Nuxt 4 breaking changes with a single flag. I think that we should go ahead and ship these changes as Nuxt v4 for two reasons:

1. People are already using it. I frequently hear of teams who are using compatibilityVersion: 4 in production. This option was intended only for testing, but it has proven solid enough for production use. We want to make it official, and give these teams the protection of a stable release.
2. It will improve the migration. Having a two-stage migration from v3 -> v4, and then v4 -> v5 will make for a smoother migration. We don't yet have a final list of breaking changes for Nitro v3, and this means we can spend enough time to ensure that the Nitro upgrade is smooth, while not delaying adoption of the Nuxt changes we've planned for the last year.

What's more, going forward we're going to do our best to decouple Nuxt releases from our key dependencies, like Vite or Nitro.

What's Included?

Nuxt 4 includes all the features you've been testing with compatibilityVersion: 4:

• 🗂️ 新目录结构 - 代码放在 app/，结构更清晰，IDE 性能更佳
• 🔄 改进的数据获取 - 更智能的 useAsyncData 和 useFetch，具备更好的缓存和清理机制
• 🏷️ 一致的组件名称 - Vue DevTools 和 <KeepAlive> 现在显示与 Nuxt 自动导入相同的名称
• 📄 增强的头部管理 - 放弃 Unhead v2 的过时功能，性能更好，标签优化更佳

…以及许多其他改进，详见升级指南。我们还将发布若干额外改动，包括：

• 为采用 Vite 环境 API 做准备（使用单一开发服务器）
• 改进环境类型处理（针对服务器、客户端和共享代码）

Nitro 进展如何？

我们不会延迟 Nitro v3 的采用。我们计划 Nuxt 5 与 Nitro v3 同时发布，时间与我们最初计划一致，即使那是在 Nuxt v4 发布几个月之后。

尽管过去一年经历了延迟，Nitro 的进展非常惊人。作为整个团队，我们对 Nitro v3 和 h3 v2 的规划感到非常兴奋。

虽然 Nuxt 4 初期不会包含这些升级，但 Nuxt v4 和 Nitro v3 同步发布，将使我们在 Nuxt 5 推出时能够更彻底地测试 Nuxt 和 Nitro 在整个生态系统中的表现。

Nuxt 3 怎么办？

Nuxt 4 稳定版本首次发布后，我们会继续维护和支持 Nuxt 3 —— 并且在 Nuxt 5 发布后仍同时支持 Nuxt 3 和 Nuxt 4。我们有意将这些版本的支持周期设为 六个月，因为我们相信升级路径会很顺利。

（我发布 Nuxt 4 升级版本的主要目标是保证升级尽可能顺畅。）

不过，我会密切关注生态系统升级的速度和成效。如果出现问题，我肯定会延长那六个月的维护支持期。我们绝不希望抛弃任何用户。

这一段时间内，意味着我们会在三个版本之间积极回溯特性和修复。但我认为这很值得。毕竟——过去一年我们就是这样为 Nuxt 4 做准备的。

接下来是什么

Nuxt v4 现在处于 候选发布 (RC) 阶段！我们希望早期采用者进行测试。请向 Nuxt 或您可能使用的任何模块报告问题。

接下来几周你可以期待以下内容：

• 我们计划在 nuxt/modules 注册表中为社区模块打开 上游 PR，并为模块作者创建迁移指南。
• 我们将为 Nuxt 3 用户创建完整的 升级指南，包括破坏性更改的列表以及如何迁移。（当前的 升级指南 解释了如何启用兼容模式，但与 Nuxt 4 有一些不同之处。）
• 本月我们将 仅发布 v3 的错误修复，推迟在 v4 发布后再移植新功能。
• 我们将 更新 nuxt.com 上的文档，以允许在 3.x、4.x 和（即将）5.x 文档之间切换。
• 随着 候选发布现已上线，我们将专注于错误修复。不再预期有新功能或重大更改。
• 一旦 v4 发布，我们将把 main 分支分离到 4.x，以采用 h3 和 nitro 的边缘版本，并开始开发 Nuxt 5。

我对这个时间表感到非常兴奋 —— 感谢你们过去一年以来的耐心和信任！