把项目从 Nuxt 4.5 升到 4.6，踩到的坑记录一下。
第一个坑：NUXT_E8012
起因是混用了自动导入的 h3 helper 和新的 nuxt/server helper。
4.6 新增了 nuxt/server 导入，提供跨 Nitro v2 / v3 / 实验性 vite-server 的 Web 标准请求原语。但 helper 的签名和 h3 v1 不一样：
- createError 接收 status 和 statusText。
- headers 通过 event.res.headers 设置。
两边混用直接报 NUXT_E8012。解决办法是选一边用到底，不要在同一个项目里混。
第二个坑：环境版本
4.6 要求 Node ^22.22.3 || ^24.15.0 || >=26.0.0。项目之前跑在 Node 20，直接装不上。这一步不解决，后面所有报错都是噪音。
第三个坑：nuxt init 没了
新建项目要用 npm create nuxt@latest。老的 muscle memory 要改。
第四个坑：CLI 的 lock 文件
4.6 会在 .nuxt/ 下生成 lock 文件，用于多进程协同。如果多个 dev 进程并行跑，行为会和之前不同。CI 里并行任务的场景要留意。
升级步骤建议
第一步，升级 Node 到合规版本，清 lock 文件重装依赖。
第二步，用 npx nuxt upgrade --dedupe。
第三步，全局搜索 server 目录下的 h3 helper 引用，统一改成 nuxt/server 或统一保留 h3。
第四步，跑一遍全链路，重点看错误处理和 header 设置相关的逻辑。
第五步，如果想提前对齐 Nuxt 5 行为，开 future.compatibilityVersion: 5。
顺带验证的收益
官方称首屏速度提升 6.6 倍、安装体积减少 73%。实测下来安装体积的感知最明显，node_modules 确实小了一截。首屏提升在开发环境明显，生产环境要看具体项目。
值不值得升
如果你的项目有自定义 server 中间件，建议先在分支上完整跑一遍。改动量不大，但都是容易静默出错的地方。纯前端渲染的项目基本可以无脑升。
本文由奇幻维度内容助手整理发布，欢迎在评论区交流你的看法。