升级Next.js 15后踩了3个坑:fetch缓存改了、异步API强制、还有水合
从14到15,Next.js变了什么?
Next.js 15 相比 14,有两处绕不开的变化。第一处是 fetch 缓存的默认行为:14 版本里未配置的 fetch 会自动强缓存,15 版本改成了默认不缓存。这意味着升级后如果不做任何处理,每次请求都会直击后端接口,数据倒是实时了,服务器压力也跟着上来了。素材里直接指出了这个坑——“依赖默认值是最坑的写法,版本一升行为就反转”。第二处是 cookies、headers、params、searchParams 这些运行时 API,全部从同步改成了异步写法,调用前得加 await。这两处是升级时的硬性门槛,处理不好项目直接报错跑不起来。1
官方也意识到了迁移的痛点,提供了 codemod 工具来自动处理异步 API 的转换。运行 npx @next/codemod@canary upgrade latest 之后,cookies()、headers()、params、searchParams 这些都能自动加上 await。但素材里也提到了一类特殊情况——“在动态路由内自定义 hook 中使用 params”的场景,codemod 处理不了,得手动改。升级前最好先在本地跑一遍这个命令,看看报哪些错,心里有底再动手。2
缓存调不明白?看这两个时间戳就够了
缓存是 Next.js App Router 里最让人迷糊的一块。表面上页面刷新了内容没变,或者改完数据页面还是旧的这两种情况,对应的是不同的缓存层问题。素材里给了一个实战思路:写两个时间戳——页面渲染时间戳和接口数据响应时间戳——分别放在组件和接口返回里。页面重新渲染了但数据时间戳不动,说明命中了 Data Cache;浏览器后退时页面时间戳没变,那是客户端路由缓存复用。只有两个时间戳同时更新,才是真正的全新数据。用时间戳当调试工具,能把缓存问题可视化。3
区分清楚之后,处理方式就简单了。数据必须实时——比如用户余额、订单状态——用 cache: 'no-store',每次都打后端;数据几乎不变——比如文档、配置——用 cache: 'force-cache',一次缓存永不再请求;数据允许有几十秒延迟但要兼顾速度——用 next: { revalidate: 60 },这是最常用的场景,缓存有效期内直接返回,过期后第一个访问触发后台刷新。素材里把三种策略总结得很直接:“记住场景就不会错”。1
水合错误怎么防?
水合问题是 Next.js 15 里另一个绕不开的话题,根源在于服务端和客户端的渲染时机不一致。素材里提到,2026年 Q1 的监控数据显示,水合错误在前端问题里占比已经到 41%,其中“动态组件水合失败”从 12% 跃升至 29%,跟 React 19 的并发渲染特性关系很大。典型的坑包括:服务端渲染时用 window.location 取路由参数,客户端激活时路由已经变了;第三方库新版本引入了动态导入,服务端和客户端加载的组件版本不一致。水合问题的核心不是“修”,而是“防”——渲染时机对上就解决了一半。4
针对路由参数不一致的问题,素材里给了一个解法:采用“路由上下文隔离”策略,服务端渲染时通过 req.url 获取原始路由,客户端激活时通过 next/router 获取当前路由,两者通过唯一 ID 关联。实施之后,错误率降了 83%。针对第三方库版本问题,核心思路是让服务端和客户端加载同一个版本——可以用“双版本沙箱”机制在构建时生成组件映射表,强制两边一致。状态不同步的问题则用“状态水合预加载”模式,在服务端把 API 响应序列化到 HTML 里,客户端激活时直接反序列化。4
要不要升级?看这几个判断维度
升级收益这块,Turbopack 是被提到最多的改进。官方数据显示热更新从 500ms 降到 50ms,本地启动快 12 倍,整体构建快 4.5 倍。但素材里也泼了点冷水——说“5倍”是 HMR 专属的数字,在 Cloudflare Pages + OpenNext 的生产环境实测,GitHub Actions 构建时间从 2 分 50 秒缩到 1 分 45 秒,幅度是 38%。对小型项目来说,这个收益可能不如预期明显。素材里的原话是:“其他博客只列'5倍'这个数字,但实际要看测试环境”。2
关于什么人适合升级,素材里有几个判断维度。大型企业级应用、用 React 技术栈、需要多种渲染策略组合、打算绑定 Vercel 生态的,升级 Next.js 15 能拿到完整的工具链支持。个人项目或者小团队快速试错,Turbopack 的性能优势在简单场景里体现不出来,反而增加复杂度,不划算。素材里还有一种观点:如果项目已经稳定运行、团队对 14 版本的坑已经踩熟了,升级带来的额外工作量不一定值得。升级前先想清楚:是尝鲜新特性,还是真的需要解决现有问题。5
| 对比维度 | Next.js 14 | Next.js 15 |
|---|---|---|
| fetch 默认缓存 | 强缓存(cache: force-cache) | 不缓存(cache: no-store) |
| 运行时 API | cookies/headers/params 同步 | 全部异步,需 await |
| Turbopack | Beta 阶段 | 默认启用(dev 模式) |
| React 版本 | React 18 | React 19 |
| 迁移工具 | — | npx @next/codemod@canary upgrade latest |
表格里列的是升级时最直接碰到的技术差异。实际迁移时建议分三步走:先跑一遍 codemod 处理异步 API,再把项目里所有的 fetch 调用梳理一遍,按数据特性补上缓存策略,最后在 staging 环境跑完整测试再看缓存表现。素材里还特别提醒了一点——升级前最好先梳理现有的 revalidate 调用,15.1 版本之后废弃了一批旧 API,直接升级可能导致部分页面的缓存行为异常。6
当前文章无评论,是时候发表评论了