GitHub
Release·  

宣布 Nuxt 4.0 正式发布

Nuxt 4.0 来了！这是一次专注于开发者体验的深思熟虑的进化，拥有更好的项目组织、更智能的数据获取和改进的类型安全。
Daniel Roe

Daniel Roe

@danielroe.dev

Nuxt 4.0 来了！ 🎉

经过一年的真实环境测试，我们很高兴地宣布 Nuxt 4 的正式发布。这是一个以稳定性为核心的重大版本发行，引入了一些深思熟虑的破坏性变更，以提升开发体验。

如果你一直在关注，我们相信你会认出这些功能和变更 —— 如果你是新用户，欢迎你的加入。

🔥 新功能？

Nuxt 4 致力于让你的开发体验更加顺畅：

  • 采用新 app/ 目录结构，更清晰的项目组织
  • 更智能的数据获取 —— 我们借此机会解决了一些不一致的问题，并改进了数据层的性能
  • 更好的 TypeScript 支持 —— 通过项目级的上下文分离来区分你的项目中不同环境的代码 —— 应用代码、服务器代码、shared/ 文件夹和配置文件
  • 更快的 CLI 和开发体验 —— 采用内部 socket 和更快速的 CLI

为什么特别选择这些功能？主要是因为这类改进需要做一些技术破坏性的更改。

一般来说，我们追求无炒作的发布方式。我们并不会为了一个大版本囤积功能，而是在 Nuxt 3 的小版本中持续发布改进。

我们也花了大量时间研究如何以兼容后向的方式实现这些更改，希望这意味着大多数 Nuxt 3 项目可以以最小的努力升级。

建议你在开始之前，先阅读升级指南，了解你的应用可能受到影响的领域。

🗂️ 新的项目结构

最大的明显变化是项目的组织方式。你的应用代码现在默认放在 app/ 目录中：

my-nuxt-app/
├─ app/
│  ├─ assets/
│  ├─ components/
│  ├─ composables/
│  ├─ layouts/
│  ├─ middleware/
│  ├─ pages/
│  ├─ plugins/
│  ├─ utils/
│  ├─ app.vue
│  ├─ app.config.ts
│  └─ error.vue
├─ content/
├─ public/
├─ shared/
├─ server/
└─ nuxt.config.ts

这有助于将你的代码与 node_modules/ 和 .git/ 分开，使文件观察器运行更快（特别是在 Windows 和 Linux 上）。这也让你的 IDE 更好地识别你是在处理客户端还是服务器端代码。

不想迁移？ 没问题！Nuxt 会自动检测你现有的结构，并保持原样正常运行。

🎨 更新的 UI 模板

Nuxt 的启动模板全新版面，增强了无障碍性，设定了默认标题，并进行了模板细节的润色（#27843）。

🔄 更智能的数据获取

我们让 useAsyncData 和 useFetch 表现得更好。多个组件使用相同的 key 时自动共享数据。组件卸载时也会自动清理，你还可以使用响应式 key 来按需重新获取数据。此外，我们还增加了更多控制缓存数据使用的方式。

这些功能部分已经在 Nuxt v3 的小版本中逐步推出，而 Nuxt v4 采用了不同的默认值，未来我们还会继续改进数据层。

🔧 更好的 TypeScript 体验

Nuxt 现在为你的应用代码、服务器代码、shared/ 文件夹及构建工具代码创建了独立的 TypeScript 项目。这意味着更好的自动补全，更准确的类型推断，以及在不同上下文下更少的混淆错误。

Nuxt 4 只需要你项目根目录下一个 tsconfig.json 文件！

这是升级中最可能带来意外的单一问题，但长期来看会让你的 TypeScript 体验更加流畅。请及时反馈任何遇到的问题。🙏

⚡ 更快的 CLI 和开发体验

v4 发布同步，我们也加速了 @nuxt/cli 发展。

  • 更快的冷启动 —— 开发服务器启动明显加快
  • Node.js 编译缓存 —— 自动重用 v8 编译缓存
  • 原生文件监听 —— 使用 fs.watch API，系统资源占用更少
  • 基于 socket 的通信 —— CLI 与 Vite 开发服务器通过内部 socket 而非网络端口通信，尤其在 Windows 上降低了开销

这些提升综合起来，能极大改善你的日常开发体验，我们也会持续推出更多优化。

🚀 如何升级

尽管大版本都会带来破坏性变更，这次的主要目标之一是确保升级过程尽可能顺畅。大多数破坏性变更已通过兼容性标志测试超过一年。

大多数项目可平滑升级，但需要注意几点：

  • @nuxt/kit 不再兼容 Nuxt 2。（这对模块作者影响较大。）
  • 一些遗留工具和弃用特性已被移除。
  • 新的 TypeScript 配置可能暴露出之前隐藏的类型问题。
  • 部分模块可能需要更新才能完全兼容 Nuxt 4。

别担心 —— 对大多数破坏性变更，都有配置选项能恢复旧行为，方便你逐步调整。

1. 更新 Nuxt

推荐升级命令：

npx nuxt upgrade --dedupe

此命令还会去重你的锁文件，确保同时更新 Nuxt 依赖的其他库，尤其是 unjs 生态相关。

2. 可选步骤：使用迁移工具

我们还与 Codemod 合作，自动完成部分迁移步骤（不覆盖全部）：

npx codemod@latest nuxt/4/migration-recipe

3. 测试与调整

运行测试，确保编译正常，修复出现的问题。升级指南 中详细说明了针对不同情况的迁移步骤。

建议你完整阅读升级指南，以全面了解应用可能受影响的部分。

🗺️ 接下来？

我们计划快速发布补丁解决可能出现的问题。Nuxt 3 将继续维护更新（包括修复及从 Nuxt 4 回移特性），直到 2026 年 1 月底，所以如果你需要时间迁移，不用着急。

展望未来，我们计划尽早发布 Nuxt 5，带来 Nitro v3 和 h3 v2，实现更卓越的性能，同时采用 Vite 环境 API，带来更佳且更快的开发体验。当然，还有更多精彩功能正在路上！

除了重大版本，Nuxt 3.x 和 4.x 发行分支也将引入许多令人激动的特性，包括 SSR 流式支持（#4753）、官方无障碍模块（#23255）、内建 fetch 缓存策略（#26017）、更强类型的 fetch 调用（将在 Nitro v3 实现）、动态路由发现（#32196）、多应用支持（#21635）及更多。

❤️ 感谢

这次发布离不开许多人的贡献，特别是去年一直测试 v4 兼容模式的用户们。衷心感谢你们的帮助！

祝你在 Nuxt 4 中编程愉快！🚀

📑 完整发行说明

阅读 Nuxt v4.0.0 的完整发行说明。

非常感谢所有参与本次发布的每一位。❤️

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