从 Nuxt 3 到 Nuxt 4：一次克制而深思的进化

「进化」而非「革命」

当年从 Nuxt 2 到 Nuxt 3 是一次彻底的重写——引入 Nitro 服务引擎、自动导入、原生 TypeScript 支持。而 Nuxt 4 走的是另一条路线：它把过去一年通过 Nuxt 3 小版本陆续放出的改进沉淀下来，作为新的默认行为。

官方将其定位为以稳定性为核心的大版本，引入少量必要的破坏性变更以换取更好的开发体验。绝大多数 Nuxt 3 项目只需简单升级即可平滑迁移。整体围绕四大支柱展开：

全新的 app/ 目录布局

最直观的变化是项目组织方式。在 Nuxt 4 中，你的应用代码默认存放在 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/ 分离，文件 watcher 扫描范围更小，在 Windows 和 Linux 上提速尤为明显。
• 更好的 IDE 上下文——编辑器能更准确地判断当前文件属于客户端还是服务端代码。
• 对齐主流框架——与现代框架的目录约定保持一致，降低心智负担。

更聪明、更一致的数据层

Nuxt 团队借这次大版本,系统性地修正了 useAsyncData 与 useFetch 的若干不一致问题,并提升了性能。核心改进包括:

• 自动数据共享——多个组件使用相同 key 时,会自动共享同一份数据,避免重复请求。
• 组件卸载自动清理——当组件卸载时,相关数据被自动回收,减少内存与状态泄漏。
• 响应式 key——可以使用响应式的 key,在依赖变化时自动重新获取数据。
• 更精细的缓存控制——对「何时使用缓存数据」拥有更强的掌控力。

// 响应式 key —— id 变化时自动重新获取
const id = useRoute().params.id
const { data, refresh } = await useFetch(
  () => `/api/users/${id}`,
  { key: () => `user-${id}` }  // 相同 key 的组件共享此数据
)

需要说明的是,其中部分能力此前已经通过 Nuxt 3 的小版本陆续放出。Nuxt 4 的不同之处在于把它们设为默认行为,并在此基础上继续打磨数据层。

按上下文拆分的类型工程

Nuxt 4 会为项目中的不同上下文分别创建独立的 TypeScript 工程:应用代码、服务端代码、shared/ 目录、构建器代码各自独立。

带来的实际收益是:在不同上下文中工作时,自动补全更智能、类型推断更准确、令人困惑的错误也更少。而且——你的项目根目录只需要一个 tsconfig.json。

更快的 CLI 与开发服务器

配合 v4,Nuxt 团队同步优化了 @nuxt/cli,这些改进在日常开发中体感明显:

Nuxt 3 vs Nuxt 4 对照表

如何升级

本次大版本的一个核心目标就是让升级尽可能平滑——大部分破坏性变更在过去一年里都已通过兼容性标志(compatibility flag)开放测试。

1. 更新 Nuxt

# 同时对 lockfile 去重,拉取 unjs 生态的相关更新
npx nuxt upgrade --dedupe

2. 可选:使用自动化迁移工具

# 借助 Codemod 自动完成大部分(并非全部)结构性变更
npx codemod@latest nuxt/4/migration-recipe

3. 测试与调整

跑测试、确认构建正常,修复浮现的问题。需要重点留意的几处:

• @nuxt/kit 已移除 Nuxt 2 兼容(主要影响模块作者)。
• 部分遗留工具与已弃用特性被清理。
• 新的 TS 设置可能暴露此前隐藏的类型问题。
• 少数模块可能需要进一步更新才能完全兼容 Nuxt 4。

下一步:Nuxt 5 在路上

官方表示会较快推出 Nuxt 5,届时将带来 Nitro v3 与 h3 v2 以获得更强性能,并采用 Vite Environment API 进一步提升开发体验。

此外,许多新特性会持续进入 3.x 与 4.x 分支,例如:SSR 流式渲染、官方无障碍模块、内置 fetch 缓存策略、更强类型的 fetch 调用、动态路由发现、多应用支持等。Nuxt 3 也会持续获得维护更新(含从 v4 回填的功能),直到 2026 年 1 月底——迁移不必着急。