Nuxt 3 与 Nuxt 4 差异及迁移

48-1

Nuxt 4 不是另起炉灶重写，它和 Nuxt 3 共享同一套核心：Nitro、Vue 3、Vite、unjs 生态。绝大多数 API（useFetch、useState、defineNuxtConfig、插件、模块……）双方完全一致。所以「从 Nuxt 3 升级到 4」远没有「Nuxt 2 升 3」那么伤筋动骨。

48-2

Nuxt 4 把「源码根目录（srcDir）」默认改成了 app/。这是两个版本之间最显眼、也最影响现有项目的区别。

Nuxt 3（源码在根目录）：

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

Nuxt 4（源码在 app/ 内）：

my-app/
├── nuxt.config.ts
├── app/
│   ├── app.vue
│   ├── components/
│   ├── composables/
│   ├── pages/
│   ├── layouts/
│   ├── middleware/
│   ├── plugins/
│   ├── utils/
│   ├── assets/
│   └── public/          # 注意：public 也搬进 app 了
└── server/              # server 仍在根目录，不变

要点有三个：

1. app.vue、components/、composables/、pages/ 等全都收进 app/。
2. public/ 从根目录移到了 app/public/——这是最容易被忽略、最容易踩坑的一处。
3. server/ 和 nuxt.config.ts 仍在项目根，不动。

48-3

Nuxt 用一个叫 compatibilityVersion 的开关控制「默认行为走 3 还是 4」。它的作用不是改 API，而是改默认约定：

• 不设置时，Nuxt 3 项目保持旧布局（根目录源码）。
• 在 Nuxt 3 项目里写 future: { compatibilityVersion: 4 }，就能提前启用 Nuxt 4 的目录约定，而无须真的升级大版本。
• Nuxt 4 本身默认就是 compatibilityVersion: 4。

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 4,
  },
})

这种「先开开关、再慢慢搬文件」的方式，正是官方推荐的平滑迁移路径：先让行为对齐，再移动目录。

48-4

把 Nuxt 3 项目迁到 Nuxt 4，建议按这个顺序：

1. 升级依赖：把 nuxt 升到 4.x（如 npm i nuxt@4）。
2. 开启开关：在 nuxt.config 加 future: { compatibilityVersion: 4 }，此时仍能跑，只是默认行为变了。
3. 搬目录：新建 app/，把 app.vue、components/、composables/、pages/、layouts/、middleware/、plugins/、utils/、assets/、public/ 移进去。
4. 检查引用路径：项目内用 ~/、@/ 别名的地方不用改（别名会自动指向新的 app/）；但写死的相对路径（如 ../components/xxx）要核对。
5. 验证构建：nuxi dev 跑起来，确认页面、资源、API 都正常；再 nuxi build 过一遍。
6. 处理第三方模块：确认所用模块兼容 Nuxt 4，有报错的先看模块仓库的 issue。

48-5

Nuxt 5 仍在开发中，但你可以从 Nuxt 4.2+ 起，用 future: { compatibilityVersion: 5 } 提前体验它的破坏性变更，例如：

• 启用 Vite 新的 Environment API；
• 页面组件名与路由名归一化（更一致的 <KeepAlive> 行为）；
• clearNuxtState 重置为初始值而非 undefined；
• Vue Options API 默认从客户端包里编译掉（减小体积）；
• 更严格的副作用导入检查等。

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 5,
  },
})

48-6

日常小版本升级（比如 4.5.0 → 4.5.2）直接用官方命令：

npx nuxt upgrade

它会帮你把依赖升到最新稳定版，比手动改 package.json 省心。

48-7

不是所有人都喜欢把源码塞进 app/。Nuxt 给你留了口子：在 nuxt.config 里设 srcDir 就能自定义源码根，或者反过来，把文件留在项目根、只显式调整目录路径。还有 @/~ 别名会自动指向你设定的源码根，所以之前的 ~/components/xxx 引用不用改。

48-8

• 静态资源 404：public/ 没搬到 app/public/，引用路径不变，只动位置。
• 「目录找不到 / 组件不自动导入」：文件还在根目录，但 Nuxt 4 默认去 app/ 扫。确认已搬，或重新 nuxi dev 让它重扫。
• 某模块报 compatibilityVersion 相关错：去模块仓库看 issue，确认它支持 Nuxt 4；必要时先暂时移除该模块，跑通后再换兼容版本。
• ~ / @ 别名解析失败：检查是否重新生成了 .nuxt/tsconfig.json，重启 dev 通常就好。 日常升级和跨大版本是两回事。小版本（4.5.0 → 4.5.2）用 npx nuxt upgrade 基本无痛，主要是修 bug 和做优化；跨大版本（3 → 4、4 → 5）才有目录和默认行为的变动，需要走前面那套迁移流程。所以平时保持小版本跟进，比攒一两年一次性大升要轻松得多——改动小、出问题也好定位是哪次升级引入的。

48-9

Nuxt 3 与 4 共享核心，差异主要在目录：app/ 成为新源码根、public/ 搬进 app/、server/ 不动。靠 compatibilityVersion: 4 平滑对齐行为，再搬目录即可。下一步看常见报错与排错。

48-6 迁移的测试策略

从 Nuxt 3 迁移到 Nuxt 4，测试是保障质量的关键。建议在迁移前先建立基本的测试覆盖：至少为关键页面和核心功能编写端到端测试。迁移过程中，这些测试就是你的安全网，任何因迁移导致的功能异常都能被测试捕获。

迁移完成后，重点测试以下几个方面：服务端渲染是否正常（检查页面源码里是否包含预期内容）、数据获取是否工作（SSR 和客户端 hydration 都要测）、路由导航是否正常、中间件是否按预期执行、插件初始化是否成功。

如果项目规模较大，不建议一次性迁移所有代码。可以先把 compatibilityVersion 设为 4，逐步调整目录结构和 API 用法，每调整一部分就运行测试确认没有回退。渐进式迁移比一次性重写风险更低。

48-7 迁移过程中的常见陷阱

从 Nuxt 3 迁移到 Nuxt 4，有几个常见的陷阱值得提前了解。第一，app/ 目录迁移时，容易遗漏某些文件。建议用脚本自动检查根目录下是否还有应该移入 app/ 的文件。

第二，一些第三方模块可能还没完全适配 Nuxt 4。迁移前先检查所有依赖模块的兼容性，必要时联系模块维护者或寻找替代方案。第三，自定义的 Nitro 配置可能需要调整。Nuxt 4 对 Nitro 的集成方式有细微变化，仔细对照官方迁移指南逐项检查。

第四，测试覆盖在迁移过程中尤为重要。迁移前建立基本的端到端测试，迁移后逐一验证。任何测试失败都意味着有功能需要调整。不要跳过测试直接上线，否则可能遗漏隐蔽的回归问题。