结论先行:Nuxt 4.0 于 2025 年 7 月 15 日正式发布,它不是推倒重来,而是把过去一年在 Nuxt 3 兼容标志下验证过的改动转正——应用代码迁入 app/ 目录、数据获取层去重共享、TypeScript 按上下文拆分项目。官方明确旧目录结构仍会被自动识别,多数项目用一条升级命令加官方 codemod 即可完成迁移;真正需要人工审计的是 useAsyncData/useFetch 的默认值变化。
一、为什么值得升
Nuxt 团队这一年的策略是「不攒大招」:改进持续落在 Nuxt 3 的小版本里,大版本只收纳那些技术上必须破坏兼容的变更。这意味着 4.0 的风险远低于一般意义上的大版本升级。收益则很实在:文件监听更快(尤其 Windows 和 Linux)、IDE 能分清你在写客户端还是服务端代码、CLI 冷启动明显提速、数据层行为更可预测。另外官方给出的时间表是 Nuxt 3 维护到 2026 年 1 月底,之后安全与修复重心转向 4.x 与后续的 Nuxt 5(将引入 Nitro v3 与 h3 v2),拖得越久迁移窗口越窄。
二、新目录结构:app/ 与 shared/
默认情况下,应用源码整体搬进 app/,而 server/、public/、content/、modules/ 留在根目录:
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 物理分离,文件监听器扫描范围变小;srcDir 默认指向 app/,IDE 与 TypeScript 能按目录判断运行环境。新增的 shared/ 目录用于存放前后端共用的工具函数与类型,注意其中只能引入两端都兼容的依赖,不能把 Node 专属模块塞进去。
不想搬目录也可以:Nuxt 检测到旧结构会按原样工作。但长期维护的项目建议尽早采用新结构,迁移本身是机械操作,codemod 可以代劳。
三、数据获取层:最需要审计的部分
useAsyncData 与 useFetch 在 4 中换了一套更严格的默认值,这是升级后最容易出隐性 bug 的地方:
| 变化 | 旧行为 | 新默认 |
|---|---|---|
| 相同 key 的调用 | 各组件各持一份数据 | 共享同一份 data/error/status |
| data 响应性 | 深层响应 | shallowRef,改属性不触发更新 |
| data/error 初始值 | null | undefined |
| 组件全部卸载后 | 数据常驻 | 自动清理 |
| getCachedData | 部分场景跳过 | 每次 fetch 都调用,带 cause 上下文 |
| 响应式 key | 不支持 | 支持,变化自动重新请求 |
实操建议:全局搜索对 fetch 结果做原地 mutation 的代码(例如直接 push 数组元素后期待视图更新),改为整体替换或按调用加 { deep: true };搜索 === null 的判断,改为兼容 undefined;共享 key 的多个调用点,确认 transform、pick、default 等选项一致,否则会触发警告。预渲染场景还要注意 payload 数据跨页面共享,key 里必须包含动态路由参数,避免不同详情页拿到同一份数据。上述行为大多提供 experimental 配置可回退,但回退只是过渡手段,不建议长期依赖。
四、TypeScript 分上下文与 CLI 提速
Nuxt 4 为 app 代码、server 代码、shared/ 与构建配置分别创建独立的 TypeScript 项目,根目录只需一个 tsconfig.json。自动补全更准、跨环境误用(比如在组件里 import Node 模块)会更早暴露。官方提醒这是升级时最可能「冒出意外」的一环:以前被单一上下文掩盖的类型问题会集中显形,属于还债而非倒退。
CLI 侧的改进包括:复用 Node 的 V8 编译缓存、改用原生 fs.watch、CLI 与 Vite 开发服务器之间用内部 socket 替代网络端口通信。Windows 用户的开发服务器启动提速尤其明显。
五、升级步骤
# 1. 升级并去重 lockfile
npx nuxt upgrade --dedupe
# 2. 可选:官方迁移 codemod(搬目录 + 已知修复)
npx codemod@latest nuxt/4/migration-recipe稳妥的顺序是:先在 Nuxt 3 里打开 future: { compatibilityVersion: 4 } 跑一轮测试,提前暴露破坏点;确认关键模块都已发布 Nuxt 4 兼容版本(模块滞后是最常见的升级阻塞项);再执行升级与 codemod;最后人工核对别名路径(~ 与 @ 的指向)、KeepAlive/findComponent 的组件名(现在遵循目录加文件名的完整约定)以及数据层审计清单。升级完成后跑生产构建,并对高流量页面做 SSR 与 hydration 冒烟测试。
六、用 Nuxt 4 做商城与内容站:后端可以不用自己写
Nuxt 的 SSR 与目录分层很适合做面向搜索流量的商城前台、品牌官网和资讯站。这类项目的共性是:前端渲染讲究,后端能力却高度同质——用户登录、商品订单、支付、优惠券、文章 Banner,几乎每个项目都要重来一遍。这时可以直接对接「api工厂」这类开放 SaaS 平台:现成管理后台加全开放前后台接口,Vue/Web 端用 apifm-webapi SDK 接入,统一返回 {code,data,msg},在 useFetch 里包一层就能享受 Nuxt 4 的数据去重与 SSR 注水;不想写前端框架的页面,纯 HTML 引入 apifm.min.js 也能调同一套接口。
如果连前台都想省掉,api工厂社区还有 vueMinishop、uni-app-mall 等开源商城前端可以直接改造,项目大全见 https://www.it120.cc/help/uq920k.html 。接口能力与 SDK 用法可在 https://www.it120.cc/sdk/index.html 查阅,先在 Playground 调通再进项目,能少走很多弯路。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。