Nuxt 5 升级:这三处破坏性变更会先在线上暴露
Nuxt 5 仍在开发中,完整条目见官方 upgrade guide。下面只挑三类本地类型检查抓不到、上线后才改变行为的变更,再补 h3 v2 与 Vite 8 的硬性要求。
一、server 端 auto-import 默认关闭,且只扫 server/utils/ 顶层
Nitro v3 把 server auto-import 改成了显式开启(experimental.nitroAutoImports)。升级后 server/ 下不写 import 直接用 defineEventHandler、readBody 这类工具,会直接报未定义。
更偏门的一点:server/utils/ 现在只扫描直接位于该目录下的文件。server/utils/db/client.ts 里的导出不会自动可用,构建时会给出 NUXT_B9006 警告,提示某个被使用的符号缺少导入。处理方式二选一:在 server/utils/ 顶层文件里 re-export,或者在使用处显式 import。需要保留旧行为可开 nitroLegacy.imports。
同时 #imports 在 server 代码里已不推荐,应换成 #imports/server。包名也一起变了:nitropack → nitro,nitropack/runtime → nitro,h3 的 server 工具从 h3 → nitro/h3。
export default defineNuxtConfig({
experimental: { nitroAutoImports: true },
})
二、错误响应格式由抛错位置决定,与请求头无关
以前判断错误返回 HTML 还是 JSON,多半靠 Accept、/api/ 前缀或 Sec-Fetch-Mode。Nuxt 5 里这些全部失效,只看错误在哪儿抛出:
- 页面渲染期抛错 → 返回 HTML 错误页(带对应状态码)。即使请求是浏览器里的
fetch()/$fetch()、curl,或带了Accept: application/json,拿到的也是 HTML。 - server route 与 server middleware 抛错 → 返回 JSON。即使这次请求是浏览器导航,包括给页面路由跑的 middleware(典型是鉴权中间件)里抛的错。
_payload.json的 payload 错误仍返回 JSON。
Accept、Sec-Fetch-Mode、User-Agent 和 /api/ 前缀都不再影响格式。前端如果有 $fetch 拦截器按 content-type 分支处理错误,这里要重新对一遍。
三、缓存类 routeRules 只按路径做 key
cache、swr、isr 现在只用 path 作为缓存 key,query string 在进入 handler 之前就被丢掉。带分页、筛选参数的接口会开始互相串数据。要保留查询串,写 allowQuery:
routeRules: {
'/api/products/**': { swr: 60, allowQuery: ['page', 'sort'] },
}
allowQuery: true 表示全部保留,也可以传参数名数组。
顺带两个 pattern 变化:route rules 改用 URLPattern 语义,* 匹配任意多段,/blog/* 也会命中 /blog/2026/hello;只匹配单段要用命名参数 /blog/:slug;一个 pattern 里只能有一个 * 或 **。另外正则约束是对百分号编码后的路径做匹配,如果约束里能匹配 %,或能匹配路径中会被编码的字符([é]、空格、.、\S、[^a-z] 这类否定字符类),或者用了 \b 词边界,构建会直接失败。
h3 v2 与 session:改名、换类、换 cookie 名
错误属性统一改名:statusCode → status,statusMessage → statusText。server route 里的错误类换成 HTTPError,取代 h3 的 createError:
throw new HTTPError({ status: 400, statusText: 'Bad request' })
app/ 里 Nuxt 的 createError composable 不受影响,不用改。routeRules 里的 statusCode 也改叫 status,目前仍兼容但会打警告,后续移除。
session 有三处:useSession/getSession/updateSession/clearSession 现在属于 nuxt/server,用 iron-webcrypto 在 web-standard Request/Response 上封装,因此能跑在任意 server.builder 下;h3 helpers 签发的 session 不能被它们解封。默认 cookie 名从 h3 变成 nuxt-session,升级前登录过的用户会统一掉一次登录、拿到一个空 session,上线前要预备好这个窗口。useSession 的 password 不再是必填,没传时用 appSecret(环境变量 NUXT_APP_SECRET)派生的密钥封装。
Vite 8 是硬要求
Vite 8 必须升,配置项跟着换:vite.esbuild → vite.oxc,vite.optimizeDeps.esbuildOptions → vite.optimizeDeps.rolldownOptions,build.rollupOptions → build.rolldownOptions。CommonJS interop 行为有变,依赖里混用 CJS/ESM 的项目要单独验一遍。迁移细节见 Vite migration guide。
迁移前 grep 清单
# server 端还在用 #imports
grep -rn "['\"]#imports['\"]" server/
# server/utils 嵌套目录(这些文件不再自动导入)
find server/utils -mindepth 2 -type f
# h3 旧错误属性与 createError
grep -rn -E "statusCode|statusMessage|createError" server/
# 缓存类 routeRules,逐个确认是否需要 allowQuery
grep -rn -E "cache:|swr:|isr:" nuxt.config.ts
# session 自定义 password 的地方
grep -rn "password" server/ | grep -i session
# Vite 旧配置项
grep -rn -E "rollupOptions|esbuildOptions|vite\.esbuild" nuxt.config.ts