Next.js 16 的 SSG 与 ISR:路由表才是验收物
generateStaticParams 写错不报错只降级,一个 cookies() 让整条路由一路掉到底,revalidatePath 之后下一个请求拿到新内容、定时 ISR 却先给旧的。五个练习,每个结论都来自构建输出和响应头。
这个博客的文章页、列表页、首页都想做成静态页:文章对所有访客都一样,只在发布时才变,没必要每次请求都查一遍库。项目是 Next.js 16.3 App Router,文章存在 Postgres 里,用 Prisma 直接查库。
这篇讲的是还没开启 Cache Components 时的旧缓存模型,Next.js 16 默认用的仍是它。做了五件事:文章详情页静态化、列表分页静态化、故意让页面掉成动态、发布后按需失效、首页定时刷新。
做下来最大的体会是:SSG 相关的错误几乎都不报错,只降级。 类型检查、lint、构建全部通过,页面也能正常打开,只是不再是静态的,或者内容是错的。能发现问题的地方只有两个:pnpm build 打印的路由表,和线上响应头。
一、generateStaticParams:缺了不报错,只降级
动态路由 app/posts/[slug]/page.tsx 想在构建时生成所有文章页,要导出 generateStaticParams ,告诉 Next 有哪些 slug。
写之前先跑了一次构建,路由表是:
┌ ○ /
├ ○ /_not-found
└ ƒ /posts/[slug]
构建照样通过。Next 找不到要预渲染的 URL 列表,就把这条路由留给请求时渲染,标成 ƒ 。这正是「线上页面没被静态化」难查的原因:它不会以失败的形式提醒你。
补上之后:
└ /posts/[slug]
├ ● /posts/nextjs-16-agents-md
└ ● /posts/prisma-7-breaking-changes
● 表示由 generateStaticParams 展开的静态路径。但这里多了一篇:prisma-7-breaking-changes 是草稿。查询没加过滤,草稿的 HTML 也被生成进了构建产物,拿到 URL 就能读到未发布内容。
第一次修的时候,我把过滤条件写进了 select :
findMany({ select: { slug: true, published: true } }) // 两条都在
findMany({ select: { slug: true }, where: { published: true } }) // 一条
select 决定返回哪些列,where 决定返回哪些行。第一种写法只是让每条记录多带一个字段,一条都没少。两种写法类型完全正确,tsc 和 eslint 都拦不住,唯一的发现方式是数路由表展开了几条路径。
只过滤构建期还不够。dynamicParams 默认是 true :没被列出的 slug 被访问时,会在请求时现渲染一份。所以页面本身的查询也要带上 published: true ,查不到就 notFound() 。两道关卡缺一不可:
// 构建期:草稿不进构建产物
findMany({ select: { slug: true }, where: { published: true } })
// 请求期:漏网的草稿 URL 走 notFound()
findUnique({ where: { slug, published: true } })
为什么不直接 export const dynamicParams = false ,让没列出的 slug 一律 404?因为那样新发布的文章在重新构建之前都访问不到。保持 true ,新文章不用重新部署也能访问,代价是任意一个不存在的 slug 都会查一次库。
二、分页:类型全对,内容全错
列表页每页 5 篇。第 1 页是 /posts ,第 2 页起是 /posts/page/[page] ,同样用 generateStaticParams 生成所有页码:
├ ○ /posts
└ /posts/page/[page]
├ ● /posts/page/2
└ ● /posts/page/3
为什么不用 ?page=2 ?官方文档原话:「Using searchParams opts your page into dynamic rendering」。读查询参数就得等请求进来,整条路由会掉成 ƒ 。
路由表只能证明「静态化了」,证明不了「分页内容对」。我从构建产物里把每页的文章链接抽出来核对,第一版的结果是:
| 页 | 实际内容 |
|---|---|
/posts | agents-md、占位 01 ~ 04 |
/posts/page/2 | 占位 02 ~ 06 |
/posts/page/3 | 占位 03 ~ 07 |
三页翻完只看到 8 篇,08、09、10 一次都没出现,相邻页大面积重叠。两个 bug:
skip: currentPage应为(currentPage - 1) * 每页条数。- 第 1 页按
published排序,这是个所有行取值都相同的布尔字段,等于没排序;分页页按publishedAt排序。两页排序依据不同,skip算对了也会串。
两个都是合法的字段名、合法的数字,类型、lint、构建全过。
边界也要自己守。dynamicParams 默认 true ,没列出的页码会在请求时渲染:
| URL | 处理 | 原因 |
|---|---|---|
/posts/page/1 | 404 | 否则和 /posts 是同一份内容的两个地址 |
/posts/page/0 、-1 | 404 | 不拦的话 skip 是负数,Prisma 抛错变 500 |
/posts/page/999 | 404 | 不拦的话返回一个空列表页,状态码 200 |
/posts/page/2.0 、abc | 404 | 用 String(Number(page)) !== page 挡掉非规范写法 |
三、一个 cookies() 让页面一路掉到底
训练计划里有个实验:故意在文章页里加一行 await cookies() ,观察它从静态掉成动态。
当时库里加了 10 篇占位文章。路由表上,11 条 ● 塌成了一行 ƒ /posts/[slug] ,图例里也多出一行 ƒ (Dynamic) 。图例是按本次实际用到的符号打印的,多出这一行,扫一眼就知道有路由掉了。
线上看不到构建输出,靠响应头判断。同一个 URL,两种状态的对照:
| 响应头 | 动态 | 静态 |
|---|---|---|
x-nextjs-cache | 无 | HIT |
x-nextjs-prerender | 无 | 1 |
Cache-Control | private, no-cache, no-store, ... | s-maxage=31536000 |
Content-Length | 无 | 10714 |
Transfer-Encoding | chunked | 无 |
最后两行最直观:动态页是边渲染边发,服务器开始发的时候还不知道总长度,只能用 chunked ;静态页的 HTML 在构建时就写好在磁盘上了,长度是确定的。
还有两个更深的发现:
generateStaticParams 照样执行了。 文档原话:「During next build, generateStaticParams runs before the corresponding Layouts or Pages are generated」。它跑在页面渲染之前,那时还没碰到 cookies() 。构建日志的 Generating static pages (18/18) 前后两次数字也一样,但 prerender-manifest.json 里的路由从 18 条变成了 7 条:11 篇文章排进了生成队列,渲染时又被丢弃。所以「写了 generateStaticParams 为什么还是 ƒ」,答案永远在页面组件里。
降级是一路掉到底。 污染前,prerender-manifest.json 的 dynamicRoutes 里有 /posts/[slug] ,代表没预渲染的路径可以按需生成并缓存。污染后它直接消失,每次请求都现渲染,没有任何缓存兜底。
能不能让它根本不发生?可以用 export const dynamic = 'error' 。污染态下加上它,构建直接失败:
Error: Route /posts/[slug] with `dynamic = "error"` couldn't be rendered statically
because it used `cookies()`.
报错点名了具体 API,退出码是 1,CI 会失败。反而是 'force-static' 更危险:它不报错,而是让 cookies() 返回空,用错了就是一个永远读不到 cookie、却毫无提示的页面。
和 Nuxt 对比:Nuxt 3 用 routeRules 显式声明 prerender: true ,规则和代码分开写;Next.js 是隐式推断,扫描到 cookies() 、headers() 、searchParams 、draftMode() 就判为动态,而且有传染性,写在 layout 里会污染整棵子树。dynamic = 'error' 相当于给隐式推断补上一条显式断言。
四、发布即生效:revalidatePath
文章发布走一个 Server Action:鉴权、Zod 校验、写库、失效缓存。
唯一性要交给数据库
两个请求同时提交同一个 slug,会发生什么?我用两个后台 curl 同时发出,第一次结果很奇怪:两个都返回「创建成功」,库里却是 0 条。
原因是 prisma.post.create(...) 前面漏了 await 。Prisma 的查询是惰性的,返回的 PrismaPromise 只有被 await 或 .then() 时才真正发 SQL。漏了 await ,查询根本没执行,函数一路走到 return { ok: true } 。tsc 和 lint 都不报。
补上之后,一个成功,一个返回「该 slug 已经存在」,库里恰好 1 条。两个请求的完成时间只差约 100ms,确实是并发的。「先查有没有、再插入」在这里会失效:两个请求都会查到「不存在」,然后都去插入。所以唯一性不靠应用层检查,交给数据库的 @unique 约束,应用层只负责把冲突错误(P2002)翻译成友好的提示。
404 也会被缓存
验收「发布即生效」时,我先访问了一次还不存在的 /posts/accept-fresh-1 ,发现第二次请求是 HIT ,磁盘上真的生成了这个 slug 的 HTML。dynamicParams 为 true 时,按需渲染的结果会写进缓存,notFound() 的结果也一样。
这意味着:如果发布时漏了失效详情页,这篇文章发布后会一直显示 404,直到重新部署。所以发布 Action 里要写:
revalidatePath('/posts/[slug]', 'page')
动态路径必须带第二个参数 'page' 。不带的话,源码里只会打一条「This has no effect by default」的警告,什么都不失效。
发布后每个页面连续请求两次:
| 路径 | 发布前 | 发布后第 1 次 | 第 2 次 |
|---|---|---|---|
/posts | HIT ,5 篇 | MISS ,出现新文章 | HIT |
/posts/accept-fresh-1 | HIT (缓存的 404) | MISS ,200 | HIT |
发布后第一个请求就是新内容。
为什么这时候不能用 revalidateTag
revalidateTag('posts') 调用不报错,但什么都不会发生。文档原话:「Tags must first be assigned to cached data」。挂 tag 有两条路:fetch 的 next.tags ,或者 'use cache' 里的 cacheTag 。Prisma 走 TCP 直连数据库,不经过 fetch ;cacheTag 又要求开启 Cache Components。两条都走不通。
那 revalidatePath 为什么能用?读源码发现,它本质上也是按 tag 失效,只是用的是 Next 自动挂上的隐式 tag。构建产物的 .meta 文件里能看到:
"x-next-cache-tags": "_N_T_/layout,_N_T_/posts/layout,_N_T_/posts/[slug]/layout,
_N_T_/posts/[slug]/page,_N_T_/posts/race-me-1"
revalidatePath('/posts/[slug]', 'page') 就是失效 _N_T_/posts/[slug]/page 这个 tag,它挂在每一篇文章页上。
五、定时 ISR:第一个请求拿到的是旧内容
首页展示热门文章,按阅读量排序。阅读量随时在变,又没有一个「发布」这样的事件可以触发失效,只能定时刷新:
export const revalidate = 3600
路由表里首页变成 ○ / ,旁边多了 Revalidate 1h 、Expire 1y 两列。
为了观察行为,我临时把周期改成 10 秒,改库里的阅读量为 42,连续请求:
| 请求 | x-nextjs-cache | 页面上的阅读量 |
|---|---|---|
| 1 | HIT | 0 |
| 2(等 10 秒以上) | STALE | 0 |
| 3 | HIT | 42 |
过期后第一个请求拿到的仍然是旧页面,同时后台重建,下一个请求才是新的。这就是 stale-while-revalidate。
响应头 Cache-Control: s-maxage=10, stale-while-revalidate=31535990 。31535990 = 1 年的秒数 − 10,s-maxage 等于 revalidate ,两者之和等于 Expire 。文档没写 expireTime 的默认值,从这里反推出来是 1 年。
和第四节对照,同样是「刷新缓存」,行为正好相反:
| 下一个请求拿到 | |
|---|---|
revalidatePath | 新内容(清掉缓存,同步重建) |
定时 revalidate 过期 | 旧内容(后台重建) |
这正是面试题「ISR 的第一个请求拿到什么」的答案,而且要分清是哪种失效。首页故意没在发布 Action 里被失效:热门按阅读量排,和发布无关,每小时刷新一次就够。
回头看
五个练习里抓到的 bug 和发现,放在一起:
| 问题 | 类型 / lint / build | 怎么发现的 |
|---|---|---|
缺 generateStaticParams | 全过 | 路由表是 ƒ |
过滤写进 select | 全过 | 路由表多展开了一条 |
skip 、orderBy 写错 | 全过 | 从产物里抽链接逐页核对 |
cookies() 污染 | 全过 | 路由表、响应头、manifest |
漏 await | 全过 | 库里查不到数据 |
| 404 被缓存 | 全过 | 发布前先请求一次,再看响应头 |
SSG 的产物是构建期生成的文件,判断对错只能看这些文件和服务它们的响应头。所以这个阶段的验收物不是页面,而是那张路由表。
迁移到 Cache Components 之后,这张表又变了两次,那是另一篇文章《同一个页面的三张路由表》的内容。