nextjs-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.

Note: Next.js 16 renamed
middleware.ts
to
proxy.ts
. Verify
proxy.ts
support in your version;
middleware.ts
remains the stable API.

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

注意： Next.js 16 已将
middleware.ts
重命名为
proxy.ts
。请确认你的版本是否支持
proxy.ts
；
middleware.ts
仍是稳定 API。

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 → 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 16.1.6+ async API changes.

See async-patterns.md for:

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

Next.js 16.1.6+ 的异步 API 变更。

详见 async-patterns.md：

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

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 vs Server Actions vs 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 标签）
Polyfill（已内置）
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

Hydration 错误

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
```
重新构建特定路由