---
title: "Announcing Nuxt 4.0"
description: "Nuxt 4.0 is here! A thoughtful evolution focused on developer experience, with better project organization, smarter data fetching, and improved type safety."
canonical_url: "https://nuxt.zhcndoc.com/blog/v4"
---
# Announcing Nuxt 4.0

> Nuxt 4.0 is here! A thoughtful evolution focused on developer experience, with better project organization, smarter data fetching, and improved type safety.

**Nuxt 4.0 来了！** 🎉

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

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

## 🔥 新功能？

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

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

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

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

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

建议你在开始之前，先阅读[升级指南](https://nuxt.zhcndoc.com/docs/4.x/getting-started/upgrade)，了解你的应用可能受到影响的领域。

### 🗂️ 新的项目结构

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

```bash
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 更好地识别你是在处理客户端还是服务器端代码。

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

#### 🎨 更新的 UI 模板

Nuxt 的启动模板全新版面，增强了无障碍性，设定了默认标题，并进行了模板细节的润色（[#27843](https://github.com/nuxt/nuxt/pull/27843)）。

### 🔄 更智能的数据获取

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

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

### 🔧 更好的 TypeScript 体验

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

::tip
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

推荐升级命令：

```sh
npx nuxt upgrade --dedupe
```

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

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

我们还与 [Codemod](https://github.com/codemod-com/codemod) 合作，自动完成部分迁移步骤（不覆盖全部）：

::code-group
```bash [npm]
npx codemod@latest nuxt/4/migration-recipe
```

```bash [yarn]
yarn dlx codemod@latest nuxt/4/migration-recipe
```

```bash [pnpm]
pnpm dlx codemod@latest nuxt/4/migration-recipe
```

```bash [bun]
bun x codemod@latest nuxt/4/migration-recipe
```
::

### 3. 测试与调整

运行测试，确保编译正常，修复出现的问题。[升级指南](https://nuxt.zhcndoc.com/docs/4.x/getting-started/upgrade) 中详细说明了针对不同情况的迁移步骤。

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

## 🗺️ 接下来？

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

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

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

## ❤️ 感谢

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

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

## 📑 完整发行说明

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

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


## Sitemap

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