Next.js 16 PPR下/api/og路由构建预渲染退出日志问题

AI 小北

2026-6-11

问题描述

在Next.js 16.2.6项目中启用Partial Prerendering (PPR)：注释所有页面的export const dynamic = "force-dynamic"，并在next.config.ts中添加cacheComponents: true。构建成功且所有页面预渲染正常，但每次执行next build时会两次输出以下日志：

OpenGraph image generation failed: Error: Route /api/og needs to bail out of prerendering at this point because it used request.url. at R (app\api\og\route.tsx:60:46)
  58 | ...port async function GET(request: NextRequest) {
  59 | ...try {
> 60 | ...  const { searchParams } = new URL(request.url);
     |       
                                        ^

该路由需要读取request.url获取查询参数、request.headers获取动态主机，无法静态预渲染。日志不会导致构建失败，但会干扰输出。曾在该路由上设置export const runtime = "edge"，现已移除；不想添加export const dynamic = "force-dynamic"，认为这违背PPR的设计意图。

已尝试的操作：

移除export const runtime = "edge"——无变化
将查询参数读取逻辑移至处理器内部（原本就在其中）——无变化
用try/catch包裹（已存在）——这是预渲染退出提示，并非运行时错误

疑问：

是否可以在不使用force-dynamic的情况下，单独排除某条API路由的PPR？
这只是可忽略的无害日志，还是存在潜在问题？
是否应将OG图片路由放在单独的路由组中，并在布局层面设置export const dynamic = "force-dynamic"？

解决方案与解答

单独排除API路由PPR的方法
可以直接在app/api/og/route.tsx中设置export const dynamic = "auto"，Next.js会自动检测到该路由依赖request.url、request.headers这类动态数据，在构建时跳过预渲染，不会再输出干扰日志。PPR核心是优化页面路由的预渲染，API路由本身不需要静态预渲染，设置auto完全符合PPR的设计逻辑，无需担心违背初衷。
日志的性质与潜在问题
这只是预渲染阶段的提示信息，不会引发构建失败或运行时异常，属于无害日志。但如果频繁出现干扰构建输出，建议按上述方法消除。实际运行时该路由会正常处理请求，没有潜在功能问题。
路由组的可行性
可以将OG图片路由放入单独的路由组（例如app/(dynamic-api)/api/og/route.tsx），然后在该路由组的layout.tsx中设置export const dynamic = "force-dynamic"，这样整个路由组下的所有API路由都会强制动态，无需单独配置每个路由。这种方式适合存在多个动态API路由的场景，便于统一管理；如果仅这一个OG路由，直接在路由文件中设置dynamic = "auto"或force-dynamic会更简洁。

内容的提问来源于stack exchange，提问作者Fakhrul Islam Fuad