BibiGPT-v1 的 next-best-practices 技能:一份覆盖文件约定、RSC 边界到自托管的 Next.js 工程规范手册
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)。
避免数据瀑布的三种手段:
Promise.all并行取数;Suspense流式渲染,各区块独立加载、独立 fallback;- 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 之类错误)的三种方案:
next/dynamic+ssr: false动态导入(包只在客户端需要);next.config.js中serverExternalPackages: ['problematic-package'](包需要在服务端运行但打包有问题,如带原生绑定的sharp、bcrypt);- 写一个
'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
五个实施步骤各有硬性要求:
- 根 layout 接收 slot props:
function RootLayout({ children, modal }),在<body>中同时渲染{children}与{modal}; default.tsx不可或缺:每个并行插槽必须有default.tsx,否则硬导航(刷新、直达链接)时 Next.js 无法确定@slot渲染什么而 404。嵌套场景下(如(marketing)/@modal/)每一层都要有;- 拦截路由写 Modal 内容:
app/@modal/(.)photos/[id]/page.tsx; - 整页写直接访问内容:
app/photos/[id]/page.tsx; - 关闭 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 约定)。实际使用建议:
- 编写 App Router 页面/路由前,先对照 file-conventions 确认特殊文件命名与并行/拦截路由结构;
- 评审涉及服务端-客户端边界的代码时,逐条核对 RSC 边界三规则与序列化白名单;
- 升级 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 即目标形态); - 容器化部署时,在技能推荐的
standalone路线与仓库现行的全量拷贝路线之间按镜像体积需求取舍,并用--debug-build-paths与/_next/mcp缩短调试回路。
整套规范与 BibiGPT-v1 仓库中 proxy.ts、next.config.js、package.json、Dockerfile、docker-compose.yml 等文件共同构成了一份「规范文档 + 生产代码」的互证样本,适合作为 Next.js 工程实践的教学与评审基准。