Nuxt 4 重大更新全面解读：新特性、破坏性变更与迁移建议

Nuxt 4 的定位

Nuxt 4 不是颠覆性重写，而是 Nuxt 3 的稳定化与清理版本。它的主要目标是：

清理 Nuxt 3 时代的技术债务
将实验性特性稳定化
统一社区分裂的目录结构约定
为未来演进奠定基础

如果你已经熟悉 Nuxt 3，升级到 Nuxt 4 的学习成本很低。但某些改动会影响现有项目，需要仔细评估。

目录结构的统一

为什么需要改变

Nuxt 3 发布时，目录结构从 Nuxt 2 继承，但又引入了新概念。结果是新老约定混杂，社区实践不一致。

典型的问题：

pages/ 和 app.vue 同时存在时的行为不清晰
layouts/ 和 App Router 风格的嵌套布局混用
middleware/ 的作用范围让人困惑

Nuxt 4 的新结构

your-nuxt-app/
├── app/                    # 应用代码主目录
│   ├── components/
│   ├── composables/
│   ├── layouts/
│   ├── middleware/
│   ├── pages/
│   ├── plugins/
│   └── app.vue
├── server/                 # 服务端代码
│   ├── api/
│   ├── middleware/
│   └── plugins/
├── public/                 # 静态资源
├── content/               # Nuxt Content 内容
├── nuxt.config.ts
└── package.json

关键变化：前端代码统一移入 app/ 目录。

这意味着什么

清晰的职责划分：app/ 是客户端/通用代码，server/ 是纯服务端代码，public/ 是静态资源。

与其他框架对齐：这种结构更接近 Next.js、Remix 等框架的惯例，降低跨框架迁移成本。

构建性能提升：目录结构更清晰后，构建工具可以更好地优化。

默认配置的变化

Nitro 引擎更新

Nitro（Nuxt 的服务端引擎）进行了显著升级：

默认使用 ESM：完全拥抱 ES Modules，不再支持 CommonJS 入口。

更智能的预渲染：预渲染爬虫改进，能更准确地发现需要预渲染的页面。

边缘部署优化：对 Cloudflare Workers、Vercel Edge 等边缘环境的支持更加成熟。

TypeScript 配置

更严格的默认配置：strict: true 成为默认，之前 Nuxt 3 默认是宽松模式。

路径别名调整：~ 和 @ 别名指向 app/ 目录而非项目根目录。

运行时配置

合并 publicRuntimeConfig 和 privateRuntimeConfig：

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 私有配置（仅服务端）
    secretKey: '',

    // 公开配置（客户端可访问）
    public: {
      apiBase: ''
    }
  }
})

这个改变实际上在 Nuxt 3 中期就开始推进，Nuxt 4 彻底移除了旧 API。

组件和 Composables 的改进

组件自动导入范围

app/components/ 下的组件自动导入规则更清晰：

文件夹名成为前缀：

app/components/
├── base/
│   └── Button.vue      # <BaseButton>
├── form/
│   ├── Input.vue       # <FormInput>
│   └── Select.vue      # <FormSelect>
└── AppHeader.vue       # <AppHeader>

Composables 改进

自动导入更智能：只导入 export function 和 export const，避免导入不必要的内部工具函数。

服务端 Composables：新增 server/composables/ 目录，服务端专用逻辑有了归属。

useState 语义调整

useState 现在默认是跨组件共享的，如果只需要组件内状态，使用 useLocalState：

// 跨组件共享（行为和 Nuxt 3 一致）
const count = useState('count', () => 0)

// 组件内私有（Nuxt 4 新增）
const localCount = useLocalState(() => 0)

性能改进

构建性能

基于 Vite 5 和新版 Rollup 的优化，典型项目的构建时间减少约 20-30%。

运行时性能

更小的客户端 Bundle：核心运行时代码进一步精简，减少约 10KB（gzip 后）。

更快的 SSR 水合：优化了水合过程的调度，首屏交互更快。

智能预取：默认开启智能预取，根据网络状况和用户行为动态调整。

开发体验

更快的 HMR：热模块替换延迟降低，尤其是在大型项目中。

更好的错误信息：编译和运行时错误提示更清晰，直接指向问题代码。

迁移指南

兼容层

Nuxt 4 提供了兼容层，允许渐进式迁移：

// nuxt.config.ts
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 3  // 使用 Nuxt 3 兼容模式
  }
})

这让你可以先升级 Nuxt 版本，再逐步修改代码。

目录结构迁移

自动迁移工具：

npx nuxi@latest upgrade --force
npx nuxi migrate

nuxi migrate 会自动移动文件到新目录结构。

手动迁移步骤：

创建 app/ 目录
移动 components/、pages/、layouts/ 等到 app/ 下
更新 import 路径中的别名
更新 nuxt.config.ts 中的路径配置

配置迁移

// Nuxt 3 配置
export default defineNuxtConfig({
  publicRuntimeConfig: {
    apiBase: ''
  },
  privateRuntimeConfig: {
    secret: ''
  }
})

// Nuxt 4 配置
export default defineNuxtConfig({
  runtimeConfig: {
    secret: '',
    public: {
      apiBase: ''
    }
  }
})

常见问题

Q：必须使用新目录结构吗？ A：不是必须的。兼容层允许继续使用旧结构，但建议新项目采用新结构。

Q：我的 Nuxt 模块还能用吗？ A：大多数模块兼容。主流模块（如 Nuxt Content、Nuxt Image）会同步更新。

Q：迁移需要多长时间？ A：小型项目半天到一天，中大型项目可能需要一周的迭代。

与 Vue 3.4/3.5 的深度集成

利用 Vue 新特性

Nuxt 4 默认使用最新的 Vue 版本，可以直接使用：

defineModel：简化 v-model 实现
v-bind 短写法：减少模板冗余
响应式性能优化：自动享受 Vue 的底层优化

服务端组件改进

Nuxt 的服务端组件支持更加完善：

<!-- app/components/ServerOnlyChart.server.vue -->
<script setup>
// 这个组件只在服务端渲染
const data = await $fetch('/api/chart-data')
</script>

<template>
  <div v-html="generateChartSVG(data)" />
</template>

.server.vue 后缀的组件只在服务端渲染，代码不会发送到客户端。

生态系统更新

Nuxt Content 3

与 Nuxt 4 同步发布的 Nuxt Content 3 带来：

新的内容查询 API
更好的 TypeScript 支持
实时预览改进
Studio 深度集成

Nuxt UI 2

官方 UI 库的升级版本：

基于 Radix Vue 重构
更好的无障碍支持
主题定制更灵活
性能进一步优化

Nuxt Image 3

图片优化模块的新版本：

支持更多图片提供商
自动格式选择（AVIF/WebP/JPEG）
懒加载策略改进

是否应该升级

建议观望的情况

大型复杂项目，迁移成本高
深度依赖尚未兼容的第三方模块
项目处于关键发布周期
团队资源紧张

时间建议

GA 发布后 1-2 个月：适合小型项目和新项目
GA 发布后 3-6 个月：适合中型项目
GA 发布后 6+ 个月：适合大型/关键项目

总结

Nuxt 4 的核心价值：

方面	改进
目录结构	统一、清晰、与主流对齐
默认配置	更合理、更严格
性能	构建更快、运行时更轻
DX	错误更清晰、HMR 更快
生态	核心模块同步升级

对于 Nuxt 开发者，这是一次值得的升级。虽然有破坏性变更，但改变的方向是正确的，长期收益大于迁移成本。

相关文章推荐：