Next.js 16 的 SSG 与 ISR:路由表才是验收物

generateStaticParams 写错不报错只降级,一个 cookies() 让整条路由一路掉到底,revalidatePath 之后下一个请求拿到新内容、定时 ISR 却先给旧的。五个练习,每个结论都来自构建输出和响应头。

2026-10-10

这个博客的文章页、列表页、首页都想做成静态页:文章对所有访客都一样,只在发布时才变,没必要每次请求都查一遍库。项目是 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」。读查询参数就得等请求进来,整条路由会掉成 ƒ 。

路由表只能证明「静态化了」,证明不了「分页内容对」。我从构建产物里把每页的文章链接抽出来核对,第一版的结果是:

页实际内容
/postsagents-md、占位 01 ~ 04
/posts/page/2占位 02 ~ 06
/posts/page/3占位 03 ~ 07

三页翻完只看到 8 篇,08、09、10 一次都没出现,相邻页大面积重叠。两个 bug:

  1. skip: currentPage 应为 (currentPage - 1) * 每页条数 。
  2. 第 1 页按 published 排序,这是个所有行取值都相同的布尔字段,等于没排序;分页页按 publishedAt 排序。两页排序依据不同,skip 算对了也会串。

两个都是合法的字段名、合法的数字,类型、lint、构建全过。

边界也要自己守。dynamicParams 默认 true ,没列出的页码会在请求时渲染:

URL处理原因
/posts/page/1404否则和 /posts 是同一份内容的两个地址
/posts/page/0 、-1404不拦的话 skip 是负数,Prisma 抛错变 500
/posts/page/999404不拦的话返回一个空列表页,状态码 200
/posts/page/2.0 、abc404用 String(Number(page)) !== page 挡掉非规范写法

三、一个 cookies() 让页面一路掉到底

训练计划里有个实验:故意在文章页里加一行 await cookies() ,观察它从静态掉成动态。

当时库里加了 10 篇占位文章。路由表上,11 条 ● 塌成了一行 ƒ /posts/[slug] ,图例里也多出一行 ƒ (Dynamic) 。图例是按本次实际用到的符号打印的,多出这一行,扫一眼就知道有路由掉了。

线上看不到构建输出,靠响应头判断。同一个 URL,两种状态的对照:

响应头动态静态
x-nextjs-cache无HIT
x-nextjs-prerender无1
Cache-Controlprivate, no-cache, no-store, ...s-maxage=31536000
Content-Length无10714
Transfer-Encodingchunked无

最后两行最直观:动态页是边渲染边发,服务器开始发的时候还不知道总长度,只能用 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 次
/postsHIT ,5 篇MISS ,出现新文章HIT
/posts/accept-fresh-1HIT (缓存的 404)MISS ,200HIT

发布后第一个请求就是新内容。

为什么这时候不能用 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页面上的阅读量
1HIT0
2(等 10 秒以上)STALE0
3HIT42

过期后第一个请求拿到的仍然是旧页面,同时后台重建,下一个请求才是新的。这就是 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 之后,这张表又变了两次,那是另一篇文章《同一个页面的三张路由表》的内容。

AI 只依据本文内容回答,可能出错,请以原文为准。