BibiGPT-v1 的 next-best-practices 技能:一份覆盖文件约定、RSC 边界到自托管的 Next.js 工程规范手册

原创2026-10-14 11:50:052,188 阅读
文章标签:人工智能AI 应用大模型前端后端提示工程

BibiGPT-v1 的 next-best-practices 技能:一份覆盖文件约定、RSC 边界到自托管的 Next.js 工程规范手册

本文以仓库中的 SKILL.md 为核心,系统梳理 BibiGPT-v1 为 AI Agent 内置的 next-best-practices 技能:它由 1 个索引文档加 18 个细分参考文档组成,覆盖文件约定、RSC 边界、Next.js 15+ 异步 API、运行时选择、指令、函数、错误处理、数据模式、Route Handlers、元数据、图片/字体优化、打包、脚本、Hydration、Suspense、并行与拦截路由、自托管与调试技巧共 18 个主题。读完本文,你可以把这套规范直接用于编写或评审 Next.js 代码,并对照 BibiGPT-v1 仓库中的真实文件(proxy.ts、next.config.js、Dockerfile 等)验证每条规范的落地方式。

技能定位与文档结构

next-best-practices 是一个供 Agent 在编写或评审 Next.js 代码时遵循的规则集。SKILL.md 的 frontmatter 中声明:

name: next-best-practices
description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
user-invocable: false

其中 user-invocable: false 表示该技能不由用户直接调用,而是作为 Agent 内部的参考规范。SKILL.md 本身是索引,把 18 个主题拆分为同目录下的独立文档,每个主题文档承载完整规则、代码示例与反模式对照:

主题 参考文档
文件约定(含 v16 middleware → proxy 改名) file-conventions.md
RSC 边界检测规则 rsc-boundaries.md
Next.js 15+ 异步 API async-patterns.md
运行时选择 runtime-selection.md
指令(directives) directives.md
函数 API 速查 functions.md
错误处理 error-handling.md
数据模式 data-patterns.md
Route Handlers route-handlers.md
元数据与 OG 图片 metadata.md
图片优化 image.md
字体优化 font.md
打包问题排查 bundling.md
第三方脚本 scripts.md
Hydration 错误 hydration-error.md
Suspense 边界 suspense-boundaries.md
并行与拦截路由 parallel-routes.md
自托管 self-hosting.md
调试技巧 debug-tricks.md

BibiGPT-v1 当前依赖 next: ^16.1.6、react: 18.2.0(见 package.json),与该技能中面向 Next.js 15/16 的规则版本前提吻合。需要说明的是:BibiGPT-v1 的页面与 API 仍组织在 Pages Router(pages/ 目录,含 _app.tsx、_document.tsx 等),因此下文会把技能中的 App Router 规则与仓库现状区分开:规则本身面向 App Router 的代码编写与评审,仓库中已落地的部分则给出对应文件证据。

文件约定:特殊文件、路由段与 v16 的 proxy 改名

file-conventions.md 规定 App Router 采用基于文件的路由,核心特殊文件约定如下:

文件 用途
page.tsx 路由段的 UI
layout.tsx 当前段与子段的共享 UI
loading.tsx 加载 UI(Suspense 边界)
error.tsx 错误 UI(Error 边界)
not-found.tsx 404 UI
route.ts API 端点
template.tsx 类似 layout 但导航时重新渲染
default.tsx 并行路由的回退

路由段命名约定包括:

app/
├── blog/               # 静态段:/blog
├── [slug]/             # 动态段:/:slug
├── [...slug]/          # Catch-all:/a/b/c
├── [[...slug]]/        # 可选 catch-all:/ 或 /a/b/c
└── (marketing)/        # 路由组(不出现在 URL 中)

并行路由使用 @slot 目录(如 @analytics/、@sidebar/,由 layout 以 props 接收),拦截路由使用 (.)、(..)、(..)(..)、(...) 匹配器。以 _ 前缀的目录(如 app/_components/)是私有文件夹,不参与路由。

该文档最值得注意的一条是 Next.js v16 将 middleware 更名为 proxy:

版本 文件 导出函数 配置导出
v14–15 middleware.ts middleware() config
v16+ proxy.ts proxy() proxyConfig

迁移命令为 npx @next/codemod@latest upgrade。这条规则在 BibiGPT-v1 中有真实落地:仓库根目录的 proxy.ts 正是按 v16 约定实现的请求中间层——导出 proxy(req: NextRequest, context: NextFetchEvent) 函数,并在文件末尾声明:

// proxy.ts(节选)
export const proxyConfig = {
  matcher: ['/api/sumup', '/api/chat'],
}

从源码结构看,该 proxy 承担了 BibiGPT 核心的 API 防护职责:仅拦截 POST 且 content-type 为 application/json 的请求;对携带 userKey 的请求依次执行 API Key 格式校验(checkOpenaiApiKeys)、许可密钥校验(validateLicenseKey)与基于 Upstash 的 IP 级限流(ratelimitForApiKeyIps);未携带 key 的请求则走 IP 限流(ratelimitForIps),超限后再通过 createMiddlewareSupabaseClient 检查 Supabase 会话,登录用户按邮箱维度限流(ratelimitForFreeAccounts),否则返回 401;最后通过 getCacheId(videoConfig) 计算缓存键并查询 Redis,命中缓存时直接以 NextResponse.json 或纯文本流返回结果(见 proxy.ts)。这正是技能文档中「proxy 用于认证、限流、重写」的典型生产用法。

RSC 边界:三类必须拦截的非法模式

rsc-boundaries.md 定义了三条检测规则:

规则 1:客户端组件不能是 async 函数。 只有 Server Component 可以 async。错误模式是文件中同时出现 'use client' 与 async function 组件;修复方式是在父级 Server Component 中完成数据获取,再把纯数据传给客户端组件:

// 错误:async client component
'use client'
export default async function UserProfile() {
  const user = await getUser() // 客户端组件中不能 await
  return <div>{user.name}</div>
}

// 正确:page.tsx(server component)
export default async function Page() {
  const user = await getUser()
  return <UserProfile user={user} />
}

规则 2:Server → Client 的 props 必须可 JSON 序列化。 禁止传递:函数('use server' 的 Server Action 除外)、Date 对象、Map/Set/WeakMap/WeakSet、类实例、Symbol、循环引用。典型陷阱是 Date 会被静默序列化为字符串,导致客户端调用 .getFullYear() 时崩溃;文档给出的修复是在服务端先 post.createdAt.toISOString() 再传递,客户端用 new Date(...) 还原。Map/Set 应转换为 Object.fromEntries(map) 或 Array.from(set),类实例应退化为纯对象({ id, name })。

规则 3:Server Action 是唯一例外。 标记 'use server' 的函数可以传给客户端组件作为 prop,例如 form action={submitForm}。

文档附带的快速对照表:

模式 合法? 修复
'use client' + async function 否 在父级 server 取数后传数据
传 () => {} 给 client 否 在客户端定义,或用 server action
传 new Date() 给 client 否 用 .toISOString()
传 new Map() 给 client 否 转为 object/array
传类实例给 client 否 传纯对象
传 server action 给 client 是 -
传 string/number/boolean、纯对象/数组 是 -

异步模式:Next.js 15+ 的 Promise 化请求 API

async-patterns.md 的核心结论:Next.js 15+ 中 params、searchParams、cookies()、headers() 全部变为异步,必须声明为 Promise 并 await。

页面与 Layout 中:

type Props = { params: Promise<{ slug: string }> }

export default async function Page({ params }: Props) {
  const { slug } = await params
}

Route Handler 中同理:

export async function GET(request: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
}

需要同时读取查询参数的页面:

type Props = {
  params: Promise<{ slug: string }>
  searchParams: Promise<{ query?: string }>
}

export default async function Page({ params, searchParams }: Props) {
  const { slug } = await params
  const { query } = await searchParams
}

对于非 async 的同步组件,文档推荐 React 19 的 use 钩子解包 Promise:

import { use } from 'react'

export default function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = use(params)
}

generateMetadata 同样接收 Promise 形式的 params 并 await 后返回 Metadata。对于仍在使用同步 API 的旧代码,官方提供的迁移 codemod 为:

npx @next/codemod@latest next-async-request-api .

对照仓库现状:BibiGPT-v1 的 API 路由 pages/api/sumup.ts 与 pages/api/chat.ts 属于 Pages Router 的 NextApiRequest/NextApiResponse 风格,直接读取 req.body、req.method,不涉及 params: Promise 这一 App Router 约定;但两个 handler 都体现了与技能一致的数据流工程习惯——入口处先校验方法与环境变量(如 Missing env var for OpenAI-compatible provider API key),再对 SummarizeRequestError 做状态码透传、其他异常统一降级为 500 JSON。

运行时选择:默认 Node.js,Edge 需满足条件

runtime-selection.md 的立场非常明确:新路由与页面默认使用 Node.js 运行时,仅当项目已使用 Edge 或有明确需求时才声明 export const runtime = 'edge'。

  • Node.js 运行时(默认):完整 Node API、文件系统(fs)、完整 crypto、数据库连接、绝大多数 npm 包可用。
  • Edge 运行时:仅限对边缘节点延迟有特定要求的场景;API 受限(无 fs、crypto 受限)、冷启动更小、具备地理分布能力。

文档要求在添加 runtime = 'edge' 前先确认三件事:项目是否已在用 Edge、是否存在具体延迟需求、所有依赖是否 Edge 兼容;不确定就用 Node.js。BibiGPT-v1 的 API 路由(OpenAI 兼容流式请求、Redis 缓存查询、Supabase 会话校验)都依赖 Node.js 完整能力,仓库中也未声明任何 runtime = 'edge',与该默认策略一致。

指令:'use client'、'use server' 与 'use cache'

directives.md 区分了 React 指令与 Next.js 指令:

'use client'(React 指令) 把一个组件标记为 Client Component,是以下能力的前提:React hooks(useState、useEffect 等)、事件处理器(onClick、onChange)、浏览器 API(window、localStorage)。

'use server'(React 指令) 把函数标记为 Server Action,可以传给 Client Component 使用;既可以在模块顶层标记,也可以内联在 Server Component 内部:

export default function Page() {
  async function submit() {
    'use server'
    // Runs on server
  }
  return <form action={submit}>...</form>
}

'use cache'(Next.js 指令) 是 Cache Components 特性的一部分,用于把函数或组件的结果缓存起来;它要求 next.config.ts 中开启 cacheComponents: true,配合 cacheLife()、cacheTag()、updateTag() 使用。BibiGPT-v1 的 next.config.js 当前未开启该特性,因此这条指令在仓库中属于「按需引入」的可选能力。

函数 API 速查表

functions.md 以表格形式整理了四类函数 API。

客户端导航 hooks:

Hook 用途
useRouter 编程式导航(push、replace、back、refresh)
usePathname 获取当前路径
useSearchParams 读取 URL 查询参数
useParams 读取动态路由参数
useSelectedLayoutSegment / useSelectedLayoutSegments 获取激活的子段
useLinkStatus 检查链接预取状态
useReportWebVitals 上报 Core Web Vitals

服务端函数:

函数 用途
cookies 读写 cookies
headers 读取请求头
draftMode 预览未发布的 CMS 内容
after 在响应流式完成后执行代码
connection 在动态渲染前等待连接
userAgent 解析 User-Agent 头

Generate 函数: generateStaticParams(构建时预渲染动态路由)、generateMetadata(动态元数据)、generateViewport(动态视口配置)、generateSitemaps(大型站点多 sitemap)、generateImageMetadata(单路由多张 OG 图)。

Request/Response: NextRequest(扩展的 Request 工具类)、NextResponse(扩展的 Response 工具类)、ImageResponse(生成 OG 图片)。

文档还给出了两个高频示例:内站导航一律使用 next/link 而非 <a>,配合 usePathname 做激活态高亮;after 用于在响应返回后执行分析上报等非阻塞任务:

import { after } from 'next/server'

export async function POST(request: Request) {
  const data = await processRequest(request)
  after(async () => {
    await logAnalytics(data)
  })
  return Response.json({ success: true })
}

仓库中的对应证据:Pages Router 页面的 pages/[...slug].tsx 使用了 next/router 的 useRouter 做重定向逻辑——这是 Pages Router 的等价 API,在评审或迁移到 App Router 时应替换为 next/navigation 的 hooks。

错误处理:错误边界、导航陷阱与认证错误

error-handling.md 覆盖四组能力。

错误边界文件。 error.tsx 捕获路由段及其子段的错误,必须是 Client Component:

'use client'

export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

global-error.tsx 捕获根布局的错误,且必须包含 <html> 与 <body> 标签。错误会向上传播到最近的错误边界,形成 app/error.tsx → app/blog/error.tsx → app/blog/[slug]/error.tsx 的层级结构,根布局内的错误最终交给 global-error.tsx。

导航 API 不能放进 try-catch。 redirect()、permanentRedirect()、notFound()、forbidden()、unauthorized() 通过抛出特殊内部错误实现导航,把它们包在 try-catch 里会被误捕获导致导航失败。文档给出两种正确写法:把导航调用移出 try-catch,或在 catch 中用 unstable_rethrow(error) 重新抛出 Next.js 内部错误。

认证错误页。 调用 unauthorized() 会渲染 unauthorized.tsx(401),forbidden() 渲染 forbidden.tsx(403),用于表达「未登录」与「无权限」两种不同状态。

404。 not-found.tsx 提供自定义 404 页面,页面逻辑中对取不到的资源调用 notFound() 即会渲染最近的 not-found.tsx。

数据模式:决策树与三种数据流

data-patterns.md 首先给出决策树:

需要获取数据?
├── 在 Server Component 中?
│   └── 直接 fetch(无需 API 层)
├── 在 Client Component 中?
│   ├── 是写操作(POST/PUT/DELETE)?
│   │   └── 用 Server Action
│   └── 是读操作(GET)?
│       └── 用 Route Handler,或从 Server Component 传入
├── 需要外部 API 访问(webhook、第三方)?
│   └── 用 Route Handler
└── 需要给移动端/外部客户端提供 REST API?
    └── 用 Route Handler

模式 1:Server Component 直接取数(首选读路径)。收益:无需维护 API、无客户端-服务器瀑布、密钥留在服务端、可直连数据库。

模式 2:Server Action(首选写路径)。收益是端到端类型安全、渐进增强(无 JS 也能提交)、与 React transitions 集成;约束是仅 POST、仅限内部使用(不可被外部访问)、不能返回不可序列化数据。配合 revalidatePath / revalidateTag 完成缓存失效。

模式 3:Route Handler(对外 API)。适用:外部客户端访问、外部服务 webhook、需要 HTTP 缓存语义的 GET、需要 OpenAPI 文档的场景;反适用:内部取数(用 Server Component)与 UI 触发的写操作(用 Server Action)。

避免数据瀑布的三种手段:

  1. Promise.all 并行取数;
  2. Suspense 流式渲染,各区块独立加载、独立 fallback;
  3. Preload 模式——用 React 的 cache() 包装取数函数,preloadUser(id) 以 fire-and-forget 方式提前发起请求,页面后续 await 时大概率已就绪:
// lib/data.ts
import { cache } from 'react'

export const getUser = cache(async (id: string) => {
  return db.user.findUnique({ where: { id } })
})

export const preloadUser = (id: string) => {
  void getUser(id) // Fire and forget
}

客户端组件取数优先「从 Server Component 传入」(initialData 作 useState 初值),其次才是 useEffect 中 fetch('/api/data');用 Server Action 做读操作可行但并非设计初衷——Server Action 恒走 POST,没有 HTTP 缓存。

模式 用例 HTTP 方法 缓存
Server Component fetch 内部读 任意 完整 Next.js 缓存
Server Action 写、表单提交 仅 POST 无
Route Handler 外部 API、webhook 任意 GET 可缓存
客户端 fetch API 客户端读 任意 HTTP 缓存头

BibiGPT 的实际数据流与「Route Handler 用于外部 API」的模式吻合:浏览器端通过 pages/api/sumup.ts 发起 POST,服务端调用 buildSummarizeRequest.ts 组装 prompt、fetchOpenAIResult.ts 请求 OpenAI 兼容接口,流式结果经 writeWebStreamToNodeResponse.ts 以 text/plain; charset=utf-8 + Cache-Control: no-cache 写给 NextApiResponse;proxy.ts 中基于 getCacheId 的 Redis 命中检查则是在 API 层之外叠加的响应级缓存。

Route Handlers:route.ts 的边界与冲突规则

route-handlers.md 的关键规则:

基本用法:在 app/api/users/route.ts 中导出 GET/POST 等 HTTP 方法函数(支持 GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS),返回 Response.json(...)。

同名目录冲突:route.ts 与 page.tsx 不能出现在同一文件夹中。若某路径既要页面又要 API,必须拆成两个路径(如 app/users/page.tsx 与 app/api/users/route.ts)。

运行环境:Route Handler 处于 Server Component 类似的环境——可用 async/await、cookies()、headers() 与 Node.js API;不能用 React hooks、React DOM API 或浏览器 API。文档明确反例:在 route handler 中 import { renderToString } from 'react-dom/server' 会失败。

请求辅助:从 new URL(request.url) 取 searchParams,从 request.headers 取请求头,从 await cookies() 取 cookie。

响应辅助:Response.json(data, { status: 404 })、自定义头、Response.redirect(new URL('/login', request.url))、以 text/event-stream 返回流。

与 Server Action 的取舍:

场景 Route Handler Server Action
表单提交 否 是
UI 触发数据变更 否 是
第三方 webhook 是 否
对外 API 消费 是 否
公开 REST API 是 否
文件上传 均可 均可

元数据与 OG 图片:静态文件往往就够

metadata.md 的第一条硬性规则:metadata 对象与 generateMetadata 只能在 Server Component 中使用。若目标页面是 'use client',文档给出三条出路:去掉指令并把客户端逻辑下沉到子组件、把元数据提取到父级 Server Component layout、或拆分为「带 metadata 的 Server Component 导入 Client Component」的文件结构。

静态元数据与动态元数据:

export const metadata: Metadata = {
  title: 'Page Title',
  description: 'Page description for search engines',
}

// 动态:
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params
  const post = await getPost(slug)
  return { title: post.title, description: post.description }
}

当页面与 metadata 需要同一份数据时,用 React cache() 包装取数函数避免重复 fetch。viewport 应与 metadata 分离导出以支持流式。根 layout 中用 title: { default, template: '%s | Site Name' } 统一标题模板。

元数据文件约定(放在 app/ 或对应路由段下):

文件 用途
favicon.ico Favicon
icon.png / icon.svg App icon
apple-icon.png Apple 应用图标
opengraph-image.png OG 图
twitter-image.png Twitter 卡片图
sitemap.ts / sitemap.xml Sitemap(多 sitemap 用 generateSitemaps)
robots.ts / robots.txt Robots 指令
manifest.ts / manifest.json Web App 清单

文档的 SEO 实用结论:对大多数站点,静态元数据文件即足够——一张 opengraph-image.png 同时覆盖 Open Graph 与 Twitter(Twitter 回退到 OG),layout 中静态的 title/description 覆盖大多数页面,只有内容随页面变化时才需要 generateMetadata。BibiGPT-v1 的 public/ 目录正放了 og-image.png、og-image.jpg 与 favicon.ico,属于同一思路的静态资源方案。

动态 OG 图片使用内置的 next/og(而非 @vercel/og),且遵守三条:不使用 searchParams(改用路由 params)、默认 Node.js 运行时、ImageResponse 内只支持 Flexbox 布局与内联样式对象。generateImageMetadata 可为单个路由生成多张 OG 图;generateSitemaps 则为大型站点切分 /sitemap/0.xml、/sitemap/1.xml 等。

图片优化:next/image 与 remotePatterns

image.md 的核心要点:

  • 一律使用 next/image 替代 <img>;
  • 远程图片必须显式 width/height,或用 fill + 父容器相对定位;本地导入的图片尺寸可自动推断;
  • 远程域名必须写入 next.config.js 的 images.remotePatterns(支持 protocol、hostname、pathname,hostname 可用通配子域如 *.cdn.com);
  • sizes 属性告诉浏览器下载哪个尺寸(全宽图 sizes="100vw",三列网格 (max-width: 768px) 100vw, 33vw);
  • placeholder="blur"(本地图自动生成 blur hash,远程图需 blurDataURL)或 placeholder="empty" + 背景色防布局偏移;
  • 首屏 LCP 图加 priority,折叠线以下默认懒加载;
  • 常见错误:fill 缺 sizes 会下载最大图、用 width={16} height={9} 表示比例而非真实尺寸、远程图未配置 hostname 会报 Invalid src prop;
  • output: 'export' 静态导出时改用 unoptimized、全局 images: { unoptimized: true } 或自定义 loader(如 Cloudinary)。

这条配置规则在 BibiGPT-v1 中有完整的生产级样例,next.config.js 声明了四个远程图片域名:

images: {
  remotePatterns: [
    {
      protocol: 'https',
      hostname: process.env.SUPABASE_HOSTNAME || 'xxxx.supabase.co', // to prevent vercel failed
    },
    { protocol: 'https', hostname: 'b.jimmylv.cn' },
    { protocol: 'https', hostname: 'bibigpt.co' },
    { protocol: 'https', hostname: 'avatars.dicebear.com' },
  ],
},

其中 Supabase 域名通过环境变量 SUPABASE_HOSTNAME 注入并带兜底值,对应登录头像等用户资源场景——这正好演示了技能文档中「hostname 可来自环境变量」的灵活用法。同一配置文件还包含与后续章节相关的另外两处内容:async rewrites() 把 /api/:path* 重写到 INTERNAL_API_HOSTNAME(支持把 API 层拆分部署),并把 /blocked 重写到 /shop;以及根据 SENTRY_AUTH_TOKEN 是否存在决定是否用 withSentryConfig 包裹配置(next.config.js)。

字体优化:next/font 与 Tailwind 集成

font.md 的核心是自托管、零布局偏移:

  • Google Fonts 通过 next/font/google 导入,subsets: ['latin'] 只加载需要的字符集,variable: '--font-inter' 生成 CSS 变量挂在 <html> 上;
  • 可变字体(variable font)无需指定 weight,默认包含全部字重;非可变字体建议只列用到的字重,如 weight: ['400', '700'];
  • 本地字体用 next/font/local,src 可以是单个文件,也可以是带 weight/style 的文件数组;
  • 与 Tailwind 集成:把 CSS 变量写入 tailwind.config.js 的 fontFamily.sans,例如 sans: <a href="https://link.gitcode.com/i/3af84f49b4fc1947effe34133e301655" target="_blank">'var(--font-inter)']——BibiGPT-v1 使用 Tailwind CSS(见 [tailwind.config.js),若引入 next/font 可按此模式接入;
  • display 策略默认 swap(先显示回退字体、加载后替换),另有 auto、block、fallback、optional;
  • 反模式:手写 <link> 引入 Google Fonts(阻塞渲染、无优化)、CSS 中 @import 字体 URL、在每个组件里重复实例化字体(应在 layout 中定义一次并复用 CSS 变量)、加载全部字重。

打包:服务端不兼容包、CSS 导入与 Turbopack

bundling.md 按问题类型给出解法。

服务端不兼容包(包内部使用 window/document/localStorage,导致 ReferenceError: window is not defined 之类错误)的三种方案:

  1. next/dynamic + ssr: false 动态导入(包只在客户端需要);
  2. next.config.js 中 serverExternalPackages: ['problematic-package'](包需要在服务端运行但打包有问题,如带原生绑定的 sharp、bcrypt);
  3. 写一个 'use client' 包装组件隔离使用。

文档附常见包对照表:sharp/bcrypt/canvas 走 serverExternalPackages(或改用 bcryptjs);recharts、react-quill、mapbox-gl、monaco-editor、lottie-web 走 dynamic(..., { ssr: false })。

CSS:导入 CSS 文件(含 CSS Modules)而不是手写 <link> 标签,交给 Next.js 打包优化。

Polyfills:Next.js 已自动包含 Array.from、Object.assign、Promise、fetch、Map、Set、Symbol、URLSearchParams 等 50+ polyfill,不要从 polyfill.io 之类 CDN 再加载一遍。

ESM/CommonJS 冲突(Cannot use import statement outside a module、require() of ES Module):在 next.config.js 加 transpilePackages: ['some-esm-package']。

包体分析:Next.js 16.1+ 内置分析器 next experimental-analyze,打开交互式 UI 可按路由、环境(client/server)、类型过滤,查看模块体积、导入链与 treemap;--output 把结果保存到 .next/diagnostics/analyze 便于对比。BibiGPT-v1 的 next 版本为 ^16.1.6,满足该命令的最低版本前提。

Turbopack 迁移提示:Next.js 15+ 默认打包器为 Turbopack,自定义 webpack 配置属于 Webpack-only 写法应逐步迁离,而 serverExternalPackages、transpilePackages 与 Turbopack 兼容。

与「浏览器/服务端环境差异」相关的一条仓库实证是 package.json 中的 browser 字段:

"browser": {
  "fs": false,
  "path": false,
  "os": false
}

它把 Node 内建模块映射为 false,使打包工具在浏览器 bundle 中排除这些模块——这正是技能文档「服务端不兼容依赖」主题在 Pages Router 时代项目中的等价手段。

脚本加载:next/script 与第三方服务组件

scripts.md 的规则:

  • 一律使用 next/script 而非原生 <script>;
  • 内联脚本必须带 id,否则 Next.js 无法跟踪;
  • next/script 不要放进 next/head,它自行处理插入位置;
  • 加载策略:afterInteractive(默认,页面可交互后加载)、lazyOnload(空闲期加载)、beforeInteractive(页面可交互前加载,仅可用于根 layout 或 pages/_document.js)、worker(实验性,Web Worker 中加载);
  • Google Analytics / Tag Manager 使用 @next/third-parties 提供的 GoogleAnalytics、GoogleTagManager 组件,替代内联 gtag 脚本;YouTube 嵌入、Google Maps 也有对应组件。

快速对照表:

模式 问题 修复
<script src="..."> 无优化 用 next/script
<Script> 无 id 无法跟踪内联脚本 加 id 属性
<Script> 在 <Head> 内 位置错误 移出 Head
内联 GA/GTM 脚本 无优化 用 @next/third-parties
strategy="beforeInteractive" 用在 layout 之外 不生效 只用于根 layout

仓库侧的旁证:BibiGPT 依赖中包含 @segment/analytics-next 与 @vercel/analytics 两个分析组件(见 package.json),属于「用官方/专用组件替代裸脚本」思路的同类实践。

Hydration 错误:四类常见成因与修复

hydration-error.md 针对 “Hydration failed because the initial UI does not match” 类错误,列出四类成因。开发环境下点击报错可查看服务端/客户端的 diff。

1. 浏览器专属 API(服务端不存在 window)。修复是 mounted 检查组件:

'use client'
import { useState, useEffect } from 'react'

export function ClientOnly({ children }: { children: React.ReactNode }) {
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])
  return mounted ? children : null
}

2. 日期/时间渲染:服务端与客户端时区可能不同,new Date().toLocaleString() 直接渲染会不一致;应放在客户端 useEffect 中计算后再 setState。

3. 随机值/ID:Math.random() 生成的 id 两端不同,应改用 React useId。

4. 非法 HTML 嵌套:如 <p> 内嵌 <div> 或 <p> 嵌套 <p>,浏览器会自行修正 DOM 导致与服务端 HTML 不符;改成合法嵌套(<div><p>...</p></div>)。

此外,在 hydration 期间修改 DOM 的第三方脚本也会引发失配,统一建议用 next/script + afterInteractive 延后加载。

Suspense 边界:哪些 hooks 会导致 CSR 回退

suspense-boundaries.md 说明:缺少 Suspense 边界时,某些客户端 hooks 会让整个页面退化为客户端渲染(CSR bailout)。

// 错误:useSearchParams 无 Suspense,整个页面变成 CSR
'use client'
import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()
  return <div>Query: {searchParams.get('q')}</div>
}

// 正确:外层包 Suspense
<Suspense fallback={<div>Loading...</div>}>
  <SearchBar />
</Suspense>

usePathname 在含动态参数的路由中同样需要 Suspense 边界(若使用了 generateStaticParams 则可选)。快速参考:

Hook 是否必须 Suspense
useSearchParams() 是
usePathname() 是(动态路由)
useParams() 否
useRouter() 否

并行路由与拦截路由:Modal 模式的完整落地

parallel-routes.md 演示了如何用并行路由(@slot)+ 拦截路由((.) 匹配器)实现「站内点击弹 Modal、直达 URL 渲染整页」的双模态体验。标准目录结构:

app/
├── @modal/                    # 并行路由插槽
│   ├── default.tsx            # 必须存在!通常返回 null
│   ├── (.)photos/             # 拦截 /photos/*
│   │   └── [id]/
│   │       └── page.tsx       # Modal 内容
│   └── [...]catchall/         # 可选:兜底
│       └── page.tsx
├── photos/
│   └── [id]/
│       └── page.tsx           # 整页(直接访问)
├── layout.tsx                 # 同时渲染 children 与 @modal
└── page.tsx

五个实施步骤各有硬性要求:

  1. 根 layout 接收 slot props:function RootLayout({ children, modal }),在 <body> 中同时渲染 {children} 与 {modal};
  2. default.tsx 不可或缺:每个并行插槽必须有 default.tsx,否则硬导航(刷新、直达链接)时 Next.js 无法确定 @slot 渲染什么而 404。嵌套场景下(如 (marketing)/@modal/)每一层都要有;
  3. 拦截路由写 Modal 内容:app/@modal/(.)photos/[id]/page.tsx;
  4. 整页写直接访问内容:app/photos/[id]/page.tsx;
  5. 关闭 Modal 必须用 router.back(),而不能用 router.push('/') 或 <Link>——后两者会新增历史记录(返回键再次显示 Modal)、不能正确清除被拦截路由,且可能造成 Modal 闪烁;router.back() 则从历史中移除拦截路由、回到上一页并正确卸载 Modal。文档同时覆盖了 Esc 键与遮罩点击的 useEffect 实现。

匹配器语义表(注意匹配的是路由段而非文件系统路径):

匹配器 含义 示例
(.) 同级 @modal/(.)photos 拦截 /photos
(..) 上一级 从 /dashboard/@modal 处的 (..)settings 拦截 /settings
(..)(..) 上两级 少用
(...) 从根起 @modal/(...)photos 从任意位置拦截 /photos

硬导航(书签、刷新、分享链接直达 /photos/123)会绕过拦截路由,渲染整页而不出 Modal;若希望直达也出 Modal,需要在整页组件中主动渲染 Modal。文档还提醒:Next.js 15+ 中拦截路由页的 params 是 Promise,须按 Promise<{ id: string }> 声明并 await。

自托管:standalone 输出与 BibiGPT 的 Docker 方案

self-hosting.md 面向「离开 Vercel 部署 Next.js」的场景,核心是 output: 'standalone':

// next.config.js
module.exports = {
  output: 'standalone',
}

构建后会在 .next/standalone/ 生成仅含生产依赖的最小目录(server.js 入口 + 生产 node_modules + .next 产物),.next/static 需单独拷贝。文档给出多阶段 Dockerfile 模板(deps 阶段 npm ci、build 阶段 next build、runner 阶段只拷贝 standalone 产物)。

对照 BibiGPT-v1 的实际情况,仓库提供的 Dockerfile 采用更直接的双阶段策略:

  • builder 阶段(node:alpine):COPY . . 后 npm ci && npm run build;并支持 IS_USED_SENTRY 构建参数——默认 0 时用 sed 注释掉 next.config.js 中的 withSentryConfig 引用,使镜像不依赖 Sentry 配置;
  • runner 阶段(node:alpine):创建非 root 用户 nextjs:nodejs(UID 1001),从 builder 拷贝 .env、next.config.js、public、.next、node_modules、package.json,EXPOSE 3000 并以 CMD ["node_modules/.bin/next", "start"] 启动。

从源码结构看,该 Dockerfile 整体拷贝 node_modules 而非启用 output: 'standalone',与技能文档推荐的「最小 standalone 产物」路线不同——两者权衡在于前者实现简单且天然兼容 Pages Router 全部依赖,后者镜像更小。仓库同时提供了 docker-compose.yml:生产服务 bibigpt(构建参数 IS_USED_SENTRY: 0,端口 3000:3000)与开发服务 bibigpt-dev(使用 dev.Dockerfile,端口 3002:3000,通过 env_file: .env 注入环境变量),直接 docker compose up -d 即可启动。

与部署相关的另一份文件是 vercel.json:它把 /ios、/f、/privacy、/terms-of-use、/status、/release 等短路径 301 重定向到对应外部资源,并设置 "github": { "silent": true } 隐藏 GitHub 按钮——属于平台侧路由配置,与 next.config.js 中的 rewrites 互补(后者负责 /api/:path* 与 /blocked → /shop)。

调试技巧:/_next/mcp 端点与按路由重建

debug-tricks.md 提供了两个提效手段。

MCP 端点(开发服务器):Next.js 在开发环境暴露 /_next/mcp 端点,支持 AI 辅助调试(MCP / JSON-RPC 2.0 over HTTP POST)。Next.js 16+ 默认启用(可配合 next-devtools-mcp);Next.js < 16 需在 next.config.js 中开启 experimental.mcpServer: true。请求格式:

curl -X POST http://localhost:<port>/_next/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"get_errors","arguments":{}}}'

可用工具包括:get_errors(构建/运行时错误及源码映射堆栈)、get_routes(扫描文件系统发现全部路由,返回 appRouter 与 pagesRouter 两类,可用 routerType 参数过滤)、get_project_metadata(项目路径与 dev server 地址)、get_page_metadata(当前页渲染的 segment 树)、get_logs(开发日志文件路径 <distDir>/logs/next-development.log)、get_server_action_by_id(按 action id 定位 Server Action)。文档特别提醒:dev server 实际端口以终端输出或 package.json scripts 为准,不要想当然用 3000——BibiGPT-v1 的 package.json 中 dev 脚本为 next dev(默认 3000),而开发容器映射为 3002。

按路由重建(Next.js 16+):

# 只重建某条路由
next build --debug-build-paths "/dashboard"

# 按 glob 重建一组路由
next build --debug-build-paths "/api/*"

# 动态路由
next build --debug-build-paths "/blog/[slug]"

适用场景:不整库重建就验证某条构建修复、排查特定页面的静态生成问题、更快迭代构建错误。

小结:如何把这份技能用进日常评审

next-best-practices 的设计方式值得参考:索引文档 SKILL.md 只列主题与一句话摘要,保证 Agent 能以低成本加载全貌;每个主题文档内部统一采用「检测规则 → 错误示例 → 正确示例 → 快速对照表」的写法,规则之间互相引用(如 Route Handler 的动态 params 示例直接复用了 async-patterns 的 Promise 约定)。实际使用建议:

  1. 编写 App Router 页面/路由前,先对照 file-conventions 确认特殊文件命名与并行/拦截路由结构;
  2. 评审涉及服务端-客户端边界的代码时,逐条核对 RSC 边界三规则与序列化白名单;
  3. 升级 Next.js 15/16 时,运行 npx @next/codemod@latest next-async-request-api . 与 npx @next/codemod@latest upgrade 两个 codemod,并把 middleware.ts 更名为 proxy.ts(BibiGPT-v1 的 proxy.ts 即目标形态);
  4. 容器化部署时,在技能推荐的 standalone 路线与仓库现行的全量拷贝路线之间按镜像体积需求取舍,并用 --debug-build-paths 与 /_next/mcp 缩短调试回路。

整套规范与 BibiGPT-v1 仓库中 proxy.ts、next.config.js、package.json、Dockerfile、docker-compose.yml 等文件共同构成了一份「规范文档 + 生产代码」的互证样本,适合作为 Next.js 工程实践的教学与评审基准。

登录后查看全文
BibiGPT-v1