next-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js Best Practices

Next.js 最佳实践

Apply these rules when writing or reviewing Next.js code.

在编写或评审 Next.js 代码时，请遵循以下规则。

File Conventions

文件约定

See file-conventions.md for:

Project structure and special files
Route segments (dynamic, catch-all, groups)
Parallel and intercepting routes
Middleware rename in v16 (middleware → proxy)

请查看 file-conventions.md 了解：

项目结构与特殊文件
路由分段（动态路由、兜底路由、路由组）
并行路由与拦截路由
v16 版本中 Middleware 的重命名（middleware → proxy）

RSC Boundaries

RSC 边界

Detect invalid React Server Component patterns.

See rsc-boundaries.md for:

Async client component detection (invalid)
Non-serializable props detection
Server Action exceptions

检测无效的 React Server Component 模式。

请查看 rsc-boundaries.md 了解：

异步客户端组件检测（无效场景）
非可序列化 props 检测
Server Action 异常处理

Async Patterns

异步模式

Next.js 15+ async API changes.

See async-patterns.md for:

Async
```
params
```
and
```
searchParams
```
Async
```
cookies()
```
and
```
headers()
```
Migration codemod

Next.js 15+ 版本的异步 API 变更。

请查看 async-patterns.md 了解：

异步
```
params
```
与
```
searchParams
```
异步
```
cookies()
```
与
```
headers()
```
迁移代码转换工具（codemod）

Runtime Selection

运行时选择

See runtime-selection.md for:

Default to Node.js runtime
When Edge runtime is appropriate

请查看 runtime-selection.md 了解：

默认使用 Node.js 运行时
适合使用 Edge 运行时的场景

Directives

指令

See directives.md for:

```
'use client'
```
,
```
'use server'
```
(React)
```
'use cache'
```
(Next.js)

请查看 directives.md 了解：

```
'use client'
```
、
```
'use server'
```
（React 指令）
```
'use cache'
```
（Next.js 指令）

Functions

函数

See functions.md for:

Navigation hooks:

useRouter

usePathname

useSearchParams

useParams

Server functions:
```
cookies
```
,
```
headers
```
,
```
draftMode
```
,
```
after
```
Generate functions:
```
generateStaticParams
```
,
```
generateMetadata
```

请查看 functions.md 了解：

导航钩子：

useRouter

、

usePathname

、

useSearchParams

、

useParams

服务器函数：
```
cookies
```
、
```
headers
```
、
```
draftMode
```
、
```
after
```
生成函数：
```
generateStaticParams
```
、
```
generateMetadata
```

Error Handling

错误处理

See error-handling.md for:

```
error.tsx
```
,
```
global-error.tsx
```
,
```
not-found.tsx
```
```
redirect
```
,
```
permanentRedirect
```
,
```
notFound
```
```
forbidden
```
,
```
unauthorized
```
(auth errors)
```
unstable_rethrow
```
for catch blocks

请查看 error-handling.md 了解：

```
error.tsx
```
、
```
global-error.tsx
```
、
```
not-found.tsx
```
```
redirect
```
、
```
permanentRedirect
```
、
```
notFound
```
```
forbidden
```
、
```
unauthorized
```
（认证错误）
捕获块中使用
```
unstable_rethrow
```

Data Patterns

数据模式

See data-patterns.md for:

Server Components vs Server Actions vs Route Handlers
Avoiding data waterfalls (
```
Promise.all
```
, Suspense, preload)
Client component data fetching

请查看 data-patterns.md 了解：

Server Components、Server Actions 与 Route Handlers 的对比
避免数据瀑布（使用
```
Promise.all
```
、Suspense、预加载）
客户端组件的数据获取

Route Handlers

路由处理器

See route-handlers.md for:

```
route.ts
```
basics
GET handler conflicts with
```
page.tsx
```
Environment behavior (no React DOM)
When to use vs Server Actions

请查看 route-handlers.md 了解：

```
route.ts
```
基础用法
GET 处理器与
```
page.tsx
```
的冲突
运行环境行为（无 React DOM）
何时使用路由处理器 vs Server Actions

Metadata & OG Images

元数据与 OG 图片

See metadata.md for:

Static and dynamic metadata
```
generateMetadata
```
function
OG image generation with
```
next/og
```
File-based metadata conventions

请查看 metadata.md 了解：

静态与动态元数据
```
generateMetadata
```
函数
使用
```
next/og
```
生成 OG 图片
基于文件的元数据约定

Image Optimization

图片优化

See image.md for:

Always use
```
next/image
```
over
```
<img>
```
Remote images configuration
Responsive
```
sizes
```
attribute
Blur placeholders
Priority loading for LCP

请查看 image.md 了解：

始终使用
```
next/image
```
替代
```
<img>
```
远程图片配置
响应式
```
sizes
```
属性
模糊占位符
为 LCP 元素设置优先加载

Font Optimization

字体优化

See font.md for:

```
next/font
```
setup
Google Fonts, local fonts
Tailwind CSS integration
Preloading subsets

请查看 font.md 了解：

```
next/font
```
配置
Google Fonts、本地字体
Tailwind CSS 集成
预加载子集字体

Bundling

打包

See bundling.md for:

Server-incompatible packages
CSS imports (not link tags)
Polyfills (already included)
ESM/CommonJS issues
Bundle analysis

请查看 bundling.md 了解：

不兼容服务器的包
CSS 导入（而非 link 标签）
已内置的 Polyfills
ESM/CommonJS 兼容问题
包分析

Scripts

脚本

See scripts.md for:

```
next/script
```
vs native script tags
Inline scripts need
```
id
```
Loading strategies
Google Analytics with
```
@next/third-parties
```

请查看 scripts.md 了解：

```
next/script
```
vs 原生 script 标签
内联脚本需要设置
```
id
```
加载策略
使用
```
@next/third-parties
```
集成 Google Analytics

Hydration Errors

水化错误

See hydration-error.md for:

Common causes (browser APIs, dates, invalid HTML)
Debugging with error overlay
Fixes for each cause

请查看 hydration-error.md 了解：

常见原因（浏览器 API、日期、无效 HTML）
使用错误覆盖层调试
各原因对应的修复方案

Suspense Boundaries

Suspense 边界

See suspense-boundaries.md for:

CSR bailout with
```
useSearchParams
```
and
```
usePathname
```
Which hooks require Suspense boundaries

请查看 suspense-boundaries.md 了解：

使用
```
useSearchParams
```
和
```
usePathname
```
时的 CSR 回退
哪些钩子需要 Suspense 边界

Parallel & Intercepting Routes

并行与拦截路由

See parallel-routes.md for:

Modal patterns with
```
@slot
```
and
```
(.)
```
interceptors
```
default.tsx
```
for fallbacks
Closing modals correctly with
```
router.back()
```

请查看 parallel-routes.md 了解：

使用
```
@slot
```
和
```
(.)
```
拦截器实现模态框模式
使用
```
default.tsx
```
作为兜底
使用
```
router.back()
```
正确关闭模态框

Self-Hosting

自托管

See self-hosting.md for:

```
output: 'standalone'
```
for Docker
Cache handlers for multi-instance ISR
What works vs needs extra setup

请查看 self-hosting.md 了解：

用于 Docker 的
```
output: 'standalone'
```
配置
多实例 ISR 的缓存处理器
原生支持的功能 vs 需要额外配置的功能

Debug Tricks

调试技巧

See debug-tricks.md for:

MCP endpoint for AI-assisted debugging
Rebuild specific routes with
```
--debug-build-paths
```

请查看 debug-tricks.md 了解：

用于 AI 辅助调试的 MCP 端点
使用
```
--debug-build-paths
```
重新构建特定路由