nextjs-server-client-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js Server Components vs Client Components

Next.js Server Components 与 Client Components 对比

Overview

概述

Provide comprehensive guidance for choosing between Server Components and Client Components in Next.js App Router, including cookie/header access, searchParams handling, pathname routing, and React's 'use' API for promise unwrapping.

提供Next.js App Router中Server Components与Client Components的全面选择指南，包括cookie/header访问、searchParams处理、pathname路由以及用于解包Promise的React 'use' API。

TypeScript: NEVER Use

any

Type

TypeScript: 绝对不要使用

any

类型

CRITICAL RULE: This codebase has

@typescript-eslint/no-explicit-any

enabled. Using

any

will cause build failures.

❌ WRONG:

typescript

function handleSubmit(e: any) { ... }
const data: any[] = [];

✅ CORRECT:

typescript

function handleSubmit(e: React.FormEvent<HTMLFormElement>) { ... }
const data: string[] = [];

关键规则： 此代码库已启用

@typescript-eslint/no-explicit-any

规则。使用

any

会导致构建失败。

❌ 错误示例：

typescript

function handleSubmit(e: any) { ... }
const data: any[] = [];

✅ 正确示例：

typescript

function handleSubmit(e: React.FormEvent<HTMLFormElement>) { ... }
const data: string[] = [];

Common Next.js Type Patterns

常见Next.js类型模式

typescript

// Page props
function Page({ params }: { params: { slug: string } }) { ... }
function Page({ searchParams }: { searchParams: { [key: string]: string | string[] | undefined } }) { ... }

// Form events
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => { ... }
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => { ... }

// Server actions
async function myAction(formData: FormData) { ... }

typescript

// 页面属性
function Page({ params }: { params: { slug: string } }) { ... }
function Page({ searchParams }: { searchParams: { [key: string]: string | string[] | undefined } }) { ... }

// 表单事件
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => { ... }
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => { ... }

// 服务器操作
async function myAction(formData: FormData) { ... }

When to Use This Skill

何时使用本指南

Use this skill when:

Deciding whether to use Server or Client Components
Accessing cookies, headers, or other server-side data
Working with searchParams or route parameters
Needing pathname or routing information
Unwrapping promises with React 'use' API
Debugging 'use client' boundary issues
Optimizing component rendering strategy

在以下场景使用本指南：

决定使用Server还是Client Components时
访问cookies、headers或其他服务器端数据时
处理searchParams或路由参数时
需要pathname或路由信息时
使用React 'use' API解包Promise时
调试'use client'边界问题时
优化组件渲染策略时

Core Decision: Server vs Client Components

核心决策：Server vs Client Components

Default: Server Components

默认选择：Server Components

All components in the App Router are Server Components by default. No directive needed.

typescript

// app/components/ProductList.tsx
// This is a Server Component (default)
export default async function ProductList() {
  const products = await fetch('https://api.example.com/products');
  const data = await products.json();

  return (
    <ul>
      {data.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

When to use Server Components:

Fetching data from APIs or databases
Accessing backend resources (environment variables, file system)
Processing sensitive information (API keys, tokens)
Reducing client-side JavaScript bundle
SEO-critical content rendering
Static or infrequently changing content

Benefits:

Zero client-side JavaScript by default
Direct database/API access
Secure handling of secrets
Automatic code splitting
Better initial page load performance
Reduced bundle size

App Router中的所有组件默认都是Server Components，无需添加任何指令。

typescript

// app/components/ProductList.tsx
// 这是一个Server Component（默认）
export default async function ProductList() {
  const products = await fetch('https://api.example.com/products');
  const data = await products.json();

  return (
    <ul>
      {data.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

何时使用Server Components：

从API或数据库获取数据时
访问后端资源（环境变量、文件系统）时
处理敏感信息（API密钥、令牌）时
减少客户端JavaScript包体积时
渲染对SEO至关重要的内容时
渲染静态或不常变更的内容时

优势：

默认无需客户端JavaScript
可直接访问数据库/API
安全处理机密信息
自动代码分割
初始页面加载性能更优
包体积更小

Client Components: 'use client'

Client Components：使用'use client'指令

Add

'use client'

directive at the top of a file to make it a Client Component.

typescript

// app/components/Counter.tsx
'use client';

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

When to use Client Components:

Need React hooks (useState, useEffect, useContext, etc.)
Event handlers (onClick, onChange, onSubmit, etc.)
Browser-only APIs (window, localStorage, navigator)
Third-party libraries requiring browser environment
Interactive UI elements (modals, dropdowns, forms)
Real-time features (WebSocket, animations)

Requirements for Client Components:

Must have
```
'use client'
```
directive at top of file
Cannot use async/await directly in component
Cannot access server-only APIs (cookies, headers)
All imported components become Client Components

在文件顶部添加

'use client'

指令，即可将组件设为Client Component。

typescript

// app/components/Counter.tsx
'use client';

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

何时使用Client Components：

需要使用React钩子（useState、useEffect、useContext等）时
需要事件处理函数（onClick、onChange、onSubmit等）时
需要浏览器专属API（window、localStorage、navigator）时
需要依赖浏览器环境的第三方库时
需要交互式UI元素（模态框、下拉菜单、表单）时
需要实时功能（WebSocket、动画）时

Client Components的要求：

必须在文件顶部添加
```
'use client'
```
指令
不能在组件中直接使用async/await
不能访问服务器专属API（cookies、headers）
所有导入的组件都会变为Client Components

⚠️ CRITICAL: Server Components NEVER Need 'use client'

⚠️ 关键注意：Server Components永远不需要'use client'

Server Components are the DEFAULT. DO NOT add 'use client' unless you specifically need client-side features.

✅ CORRECT - Server Component with Navigation:

typescript

// app/page.tsx - Server Component (NO 'use client' needed!)
import Link from 'next/link';
import { redirect } from 'next/navigation';

export default async function Page() {
  // Server components can be async
  const data = await fetchData();

  if (!data) {
    redirect('/login');  // Server-side redirect
  }

  return (
    <div>
      <Link href="/dashboard">Go to Dashboard</Link>
      <p>{data.content}</p>
    </div>
  );
}

❌ WRONG - Adding 'use client' to Server Component:

typescript

// app/page.tsx
'use client';  // ❌ WRONG! Don't add this to server components!

export default async function Page() {  // ❌ Will fail - async client components not allowed
  const data = await fetchData();
  return <div>{data.content}</div>;
}

Server Navigation Methods (NO 'use client' needed):

```
<Link>
```
component from
```
next/link
```
```
redirect()
```
function from
```
next/navigation
```
Server Actions (see Advanced Routing skill)

Client Navigation Methods (REQUIRES 'use client'):

```
useRouter()
```
hook from
```
next/navigation
```
```
usePathname()
```
hook
```
useSearchParams()
```
hook (also requires Suspense)

Server Components是默认选项。除非明确需要客户端特性，否则不要添加'use client'。

✅ 正确示例 - 包含导航的Server Component：

typescript

// app/page.tsx - Server Component（无需'use client'！）
import Link from 'next/link';
import { redirect } from 'next/navigation';

export default async function Page() {
  // Server Components可以是异步的
  const data = await fetchData();

  if (!data) {
    redirect('/login');  // 服务器端重定向
  }

  return (
    <div>
      <Link href="/dashboard">前往仪表盘</Link>
      <p>{data.content}</p>
    </div>
  );
}

❌ 错误示例 - 给Server Component添加'use client'：

typescript

// app/page.tsx
'use client';  // ❌ 错误！不要给Server Components添加这个！

export default async function Page() {  // ❌ 会失败 - 不允许异步Client Components
  const data = await fetchData();
  return <div>{data.content}</div>;
}

服务器端导航方法（无需'use client'）：

来自
```
next/link
```
的
```
<Link>
```
组件
来自
```
next/navigation
```
的
```
redirect()
```
函数
服务器操作（参考高级路由指南）

客户端导航方法（需要'use client'）：

来自
```
next/navigation
```
的
```
useRouter()
```
钩子
```
usePathname()
```
钩子
```
useSearchParams()
```
钩子（同时需要Suspense）

Server Component Patterns

Server Component模式

Accessing Cookies

访问Cookies

Use

next/headers

to read cookies in Server Components:

typescript

// app/dashboard/page.tsx
import { cookies } from 'next/headers';

export default async function Dashboard() {
  const cookieStore = await cookies();
  const token = cookieStore.get('session-token');

  if (!token) {
    redirect('/login');
  }

  const user = await fetchUser(token.value);

  return <div>Welcome, {user.name}</div>;
}

Important Notes:

```
cookies()
```
must be awaited in Next.js 15+
Cookies are read-only in Server Components
To set cookies, use Server Actions (see Advanced Routing skill)
Cookie access is only available in Server Components

在Server Components中使用

next/headers

读取cookies：

typescript

// app/dashboard/page.tsx
import { cookies } from 'next/headers';

export default async function Dashboard() {
  const cookieStore = await cookies();
  const token = cookieStore.get('session-token');

  if (!token) {
    redirect('/login');
  }

  const user = await fetchUser(token.value);

  return <div>欢迎，{user.name}</div>;
}

重要说明：

Next.js 15+中
```
cookies()
```
必须使用await
Server Components中Cookies是只读的
如需设置Cookies，请使用服务器操作（参考高级路由指南）
仅Server Components可访问Cookies

Accessing Headers

访问Headers

typescript

// app/api/route.ts or any Server Component
import { headers } from 'next/headers';

export default async function Page() {
  const headersList = await headers();
  const userAgent = headersList.get('user-agent');
  const referer = headersList.get('referer');

  return <div>User Agent: {userAgent}</div>;
}

typescript

// app/api/route.ts 或任意Server Component
import { headers } from 'next/headers';

export default async function Page() {
  const headersList = await headers();
  const userAgent = headersList.get('user-agent');
  const referer = headersList.get('referer');

  return <div>用户代理：{userAgent}</div>;
}

Using searchParams

使用searchParams

Access URL query parameters directly in Server Components:

typescript

// app/search/page.tsx
export default async function SearchPage({
  searchParams,
}: {
  searchParams: { q?: string; category?: string };
}) {
  const query = searchParams.q || '';
  const category = searchParams.category || 'all';

  const results = await searchProducts(query, category);

  return (
    <div>
      <h1>Search Results for: {query}</h1>
      <p>Category: {category}</p>
      <ProductList products={results} />
    </div>
  );
}

Important Notes:

```
searchParams
```
is only available in
```
page.tsx
```
files
In Next.js 15+,
```
searchParams
```
must be awaited
searchParams is NOT available in
```
layout.tsx
```
Use client-side
```
useSearchParams()
```
hook if needed in Client Components

⚠️ CRITICAL WARNING - Next.js 15+ searchParams: When extracting parameters in Next.js 15+, you MUST use destructuring to keep the

searchParams

identifier visible in the same line as the parameter extraction. Do NOT use intermediate variables like

params

resolved

- this is an anti-pattern that breaks code readability and testing patterns.

Async searchParams (Next.js 15+):

typescript

// app/search/page.tsx (Next.js 15+)
export default async function SearchPage({
  searchParams,
}: {
  searchParams: Promise<{ q?: string }>;
}) {
  // BEST PRACTICE: Inline access keeps searchParams and parameter together on one line
  const q = (await searchParams).q || '';

  return <div>Search: {q}</div>;
}

CRITICAL PATTERN REQUIREMENT:

When extracting parameters from

searchParams

, ALWAYS use inline access to keep

searchParams

and the parameter name on the SAME LINE:

typescript

// ✅ CORRECT: Inline access (REQUIRED PATTERN)
const name = (await searchParams).name || '';

// ✅ ALSO CORRECT: Multiple parameters
const category = (await searchParams).category || 'all';
const sort = (await searchParams).sort || 'asc';

// ❌ WRONG: Using intermediate variable separates searchParams from parameter
const params = await searchParams;  // DON'T DO THIS
const name = params.name;           // searchParams not visible here

// ❌ WRONG: Destructuring (searchParams and name on same line but missing second 'name')
const { name } = await searchParams;  // Not preferred

Why inline access:

Keeps
```
searchParams
```
identifier visible on the same line as parameter extraction
Makes the relationship between URL parameter and variable explicit
Satisfies code review and testing patterns that check for proper searchParams usage

在Server Components中直接访问URL查询参数：

typescript

// app/search/page.tsx
export default async function SearchPage({
  searchParams,
}: {
  searchParams: { q?: string; category?: string };
}) {
  const query = searchParams.q || '';
  const category = searchParams.category || 'all';

  const results = await searchProducts(query, category);

  return (
    <div>
      <h1>搜索结果：{query}</h1>
      <p>分类：{category}</p>
      <ProductList products={results} />
    </div>
  );
}

重要说明：

```
searchParams
```
仅在
```
page.tsx
```
文件中可用
Next.js 15+中
```
searchParams
```
必须使用await
```
searchParams
```
在
```
layout.tsx
```
中不可用
如需在Client Components中使用，请使用客户端
```
useSearchParams()
```
钩子

⚠️ 关键警告 - Next.js 15+的searchParams： 在Next.js 15+中提取参数时，必须使用解构方式，确保

searchParams

标识符与参数提取在同一行可见。不要使用

params

或

resolved

等中间变量，这是违反代码可读性和测试模式的反模式。

异步searchParams（Next.js 15+）：

typescript

// app/search/page.tsx (Next.js 15+)
export default async function SearchPage({
  searchParams,
}: {
  searchParams: Promise<{ q?: string }>;
}) {
  // 最佳实践：内联访问使searchParams和参数在同一行可见
  const q = (await searchParams).q || '';

  return <div>搜索：{q}</div>;
}

关键模式要求：

从

searchParams

提取参数时，必须始终使用内联访问，确保

searchParams

标识符与参数名称在同一行：

typescript

// ✅ 正确：内联访问（要求的模式）
const name = (await searchParams).name || '';

// ✅ 正确：多个参数
const category = (await searchParams).category || 'all';
const sort = (await searchParams).sort || 'asc';

// ❌ 错误：使用中间变量分离searchParams与参数
const params = await searchParams;  // 不要这样做
const name = params.name;           // 此处看不到searchParams

// ❌ 错误：解构（searchParams和name在同一行但缺少第二个'name'）
const { name } = await searchParams;  // 不推荐

为什么使用内联访问：

使
```
searchParams
```
标识符与参数提取在同一行可见
明确URL参数与变量之间的关系
符合代码审查和测试模式对searchParams正确使用的要求

Using pathname and Route Information

使用pathname和路由信息

In Server Components (page.tsx):

typescript

// app/blog/[slug]/page.tsx
export default async function BlogPost({
  params,
}: {
  params: { slug: string };
}) {
  // params contains route parameters
  const post = await getPost(params.slug);

  return <article>{post.title}</article>;
}

Async params (Next.js 15+):

typescript

// app/blog/[slug]/page.tsx (Next.js 15+)
export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);

  return <article>{post.title}</article>;
}

In Client Components:

Use hooks from

next/navigation

typescript

// app/components/Breadcrumbs.tsx
'use client';

import { usePathname, useParams, useSearchParams } from 'next/navigation';

export default function Breadcrumbs() {
  const pathname = usePathname(); // Current path: /blog/hello-world
  const params = useParams(); // Route params: { slug: 'hello-world' }
  const searchParams = useSearchParams(); // Query params

  return (
    <nav>
      <span>Current path: {pathname}</span>
      <span>Slug: {params.slug}</span>
      <span>Search: {searchParams.get('q')}</span>
    </nav>
  );
}

在Server Components（page.tsx）中：

typescript

// app/blog/[slug]/page.tsx
export default async function BlogPost({
  params,
}: {
  params: { slug: string };
}) {
  // params包含路由参数
  const post = await getPost(params.slug);

  return <article>{post.title}</article>;
}

异步params（Next.js 15+）：

typescript

// app/blog/[slug]/page.tsx (Next.js 15+)
export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);

  return <article>{post.title}</article>;
}

在Client Components中：

使用

next/navigation

中的钩子：

typescript

// app/components/Breadcrumbs.tsx
'use client';

import { usePathname, useParams, useSearchParams } from 'next/navigation';

export default function Breadcrumbs() {
  const pathname = usePathname(); // 当前路径：/blog/hello-world
  const params = useParams(); // 路由参数：{ slug: 'hello-world' }
  const searchParams = useSearchParams(); // 查询参数

  return (
    <nav>
      <span>当前路径：{pathname}</span>
      <span>Slug：{params.slug}</span>
      <span>搜索：{searchParams.get('q')}</span>
    </nav>
  );
}

⚠️ CRITICAL: useSearchParams ALWAYS Requires Suspense

⚠️ 关键注意：useSearchParams始终需要Suspense

When using
useSearchParams()
hook, you MUST:

Add
```
'use client'
```
directive at the top of the file
Wrap the component in a Suspense boundary

This is a Next.js requirement - failing to do both will cause errors.

✅ CORRECT Pattern:

typescript

// app/page.tsx or any parent component
import { Suspense } from 'react';
import SearchComponent from './SearchComponent';

export default function Page() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <SearchComponent />
    </Suspense>
  );
}

// app/SearchComponent.tsx
'use client';

import { useSearchParams } from 'next/navigation';

export default function SearchComponent() {
  const searchParams = useSearchParams();
  const query = searchParams.get('q');

  return <div>Search query: {query}</div>;
}

❌ WRONG - Missing 'use client':

typescript

// This will fail - useSearchParams requires 'use client'
import { useSearchParams } from 'next/navigation';

export default function SearchComponent() {
  const searchParams = useSearchParams(); // ERROR!
  return <div>{searchParams.get('q')}</div>;
}

❌ WRONG - Missing Suspense wrapper:

typescript

// This will cause issues - useSearchParams requires Suspense
export default function Page() {
  return <SearchComponent />; // Missing Suspense wrapper!
}

使用
useSearchParams()
钩子时，必须：

在文件顶部添加
```
'use client'
```
指令
用Suspense边界包裹组件

这是Next.js的强制要求 - 不满足这两点会导致错误。

✅ 正确模式：

typescript

// app/page.tsx 或任何父组件
import { Suspense } from 'react';
import SearchComponent from './SearchComponent';

export default function Page() {
  return (
    <Suspense fallback={<div>加载中...</div>}>
      <SearchComponent />
    </Suspense>
  );
}

// app/SearchComponent.tsx
'use client';

import { useSearchParams } from 'next/navigation';

export default function SearchComponent() {
  const searchParams = useSearchParams();
  const query = searchParams.get('q');

  return <div>搜索关键词：{query}</div>;
}

❌ 错误示例 - 缺少'use client'：

typescript

// 会失败 - useSearchParams需要'use client'
import { useSearchParams } from 'next/navigation';

export default function SearchComponent() {
  const searchParams = useSearchParams(); // 错误！
  return <div>{searchParams.get('q')}</div>;
}

❌ 错误示例 - 缺少Suspense包裹：

typescript

// 会出现问题 - useSearchParams需要Suspense
export default function Page() {
  return <SearchComponent />; // 缺少Suspense包裹！
}

React 'use' API for Promise Unwrapping

用于解包Promise的React 'use' API

The React

use

API allows reading promises and context in both Server and Client Components.

React

use

API允许在Server和Client Components中读取Promise和上下文。

Using 'use' with Promises

结合Promise使用'use'

typescript

// app/components/UserProfile.tsx
'use client';

import { use } from 'react';

// IMPORTANT: Use specific types, generic types, or 'unknown' - NEVER 'any'
// Option 1: Specific type (best when type is known)
export default function UserProfile({
  userPromise
}: {
  userPromise: Promise<{ name: string; email: string }>
}) {
  // Unwrap the promise
  const user = use(userPromise);

  return <div>{user.name}</div>;
}

// Option 2: Generic type (for reusable components)
export function GenericDataDisplay<T>({
  data
}: {
  data: Promise<T>
}) {
  const result = use(data);
  return <div>{JSON.stringify(result)}</div>;
}

// Option 3: Unknown type (when type truly unknown)
export function UnknownDataDisplay({
  data
}: {
  data: Promise<unknown>
}) {
  const result = use(data);
  return <div>{JSON.stringify(result)}</div>;
}

Server Component passing promise:

typescript

// app/profile/page.tsx
import UserProfile from './components/UserProfile';

export default function ProfilePage() {
  // Create promise but don't await
  const userPromise = fetchUser();

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <UserProfile userPromise={userPromise} />
    </Suspense>
  );
}

typescript

// app/components/UserProfile.tsx
'use client';

import { use } from 'react';

// 重要：使用特定类型、泛型类型或'unknown' - 绝对不要使用'any'
// 选项1：特定类型（已知类型时最佳）
export default function UserProfile({
  userPromise
}: {
  userPromise: Promise<{ name: string; email: string }>
}) {
  // 解包Promise
  const user = use(userPromise);

  return <div>{user.name}</div>;
}

// 选项2：泛型类型（用于可复用组件）
export function GenericDataDisplay<T>({
  data
}: {
  data: Promise<T>
}) {
  const result = use(data);
  return <div>{JSON.stringify(result)}</div>;
}

// 选项3：Unknown类型（类型未知时）
export function UnknownDataDisplay({
  data
}: {
  data: Promise<unknown>
}) {
  const result = use(data);
  return <div>{JSON.stringify(result)}</div>;
}

Server Component传递Promise：

typescript

// app/profile/page.tsx
import UserProfile from './components/UserProfile';

export default function ProfilePage() {
  // 创建Promise但不等待
  const userPromise = fetchUser();

  return (
    <Suspense fallback={<div>加载中...</div>}>
      <UserProfile userPromise={userPromise} />
    </Suspense>
  );
}

Benefits of 'use' API

'use' API的优势

Enables parallel data fetching
Works with Suspense boundaries
Allows Server Components to pass promises to Client Components
Cleaner than prop drilling async data

支持并行数据获取
与Suspense边界配合使用
允许Server Components向Client Components传递Promise
比传递异步数据的属性钻取更简洁

Using 'use' with Context

结合Context使用'use'

typescript

'use client';

import { use } from 'react';
import { ThemeContext } from './ThemeContext';

export default function ThemedButton() {
  const theme = use(ThemeContext);

  return <button className={theme.buttonClass}>Click me</button>;
}

typescript

'use client';

import { use } from 'react';
import { ThemeContext } from './ThemeContext';

export default function ThemedButton() {
  const theme = use(ThemeContext);

  return <button className={theme.buttonClass}>点击我</button>;
}

Common Patterns

常见模式

Pattern 1: Server Component Fetches, Client Component Interacts

模式1：Server Component获取数据，Client Component处理交互

typescript

// app/products/page.tsx (Server Component)
import ProductGrid from './ProductGrid';

export default async function ProductsPage() {
  const products = await fetchProducts();

  // Pass data to Client Component
  return <ProductGrid products={products} />;
}

// app/products/ProductGrid.tsx (Client Component)
'use client';

import { useState } from 'react';

export default function ProductGrid({
  products
}: {
  products: Product[]
}) {
  const [filter, setFilter] = useState('all');

  const filtered = products.filter(p =>
    filter === 'all' || p.category === filter
  );

  return (
    <div>
      <select onChange={(e) => setFilter(e.target.value)}>
        <option value="all">All</option>
        <option value="electronics">Electronics</option>
      </select>
      {filtered.map(p => <div key={p.id}>{p.name}</div>)}
    </div>
  );
}

typescript

// app/products/page.tsx (Server Component)
import ProductGrid from './ProductGrid';

export default async function ProductsPage() {
  const products = await fetchProducts();

  // 将数据传递给Client Component
  return <ProductGrid products={products} />;
}

// app/products/ProductGrid.tsx (Client Component)
'use client';

import { useState } from 'react';

export default function ProductGrid({
  products
}: {
  products: Product[]
}) {
  const [filter, setFilter] = useState('all');

  const filtered = products.filter(p =>
    filter === 'all' || p.category === filter
  );

  return (
    <div>
      <select onChange={(e) => setFilter(e.target.value)}>
        <option value="all">全部</option>
        <option value="electronics">电子产品</option>
      </select>
      {filtered.map(p => <div key={p.id}>{p.name}</div>)}
    </div>
  );
}

Pattern 2: Parallel Data Fetching

模式2：并行数据获取

typescript

// app/dashboard/page.tsx
export default async function Dashboard() {
  // Fetch in parallel
  const [user, stats, notifications] = await Promise.all([
    fetchUser(),
    fetchStats(),
    fetchNotifications(),
  ]);

  return (
    <div>
      <UserInfo user={user} />
      <Stats data={stats} />
      <Notifications items={notifications} />
    </div>
  );
}

typescript

// app/dashboard/page.tsx
export default async function Dashboard() {
  // 并行获取
  const [user, stats, notifications] = await Promise.all([
    fetchUser(),
    fetchStats(),
    fetchNotifications(),
  ]);

  return (
    <div>
      <UserInfo user={user} />
      <Stats data={stats} />
      <Notifications items={notifications} />
    </div>
  );
}

Pattern 3: Streaming with Suspense

模式3：结合Suspense的流式渲染

typescript

// app/page.tsx
import { Suspense } from 'react';

export default function Page() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<div>Loading stats...</div>}>
        <Stats />
      </Suspense>
      <Suspense fallback={<div>Loading feed...</div>}>
        <Feed />
      </Suspense>
    </div>
  );
}

async function Stats() {
  const data = await fetchStats(); // Slow query
  return <div>{data.total}</div>;
}

async function Feed() {
  const items = await fetchFeed(); // Fast query
  return <ul>{items.map(i => <li key={i.id}>{i.title}</li>)}</ul>;
}

typescript

// app/page.tsx
import { Suspense } from 'react';

export default function Page() {
  return (
    <div>
      <h1>仪表盘</h1>
      <Suspense fallback={<div>加载统计数据...</div>}>
        <Stats />
      </Suspense>
      <Suspense fallback={<div>加载动态内容...</div>}>
        <Feed />
      </Suspense>
    </div>
  );
}

async function Stats() {
  const data = await fetchStats(); // 慢查询
  return <div>{data.total}</div>;
}

async function Feed() {
  const items = await fetchFeed(); // 快查询
  return <ul>{items.map(i => <li key={i.id}>{i.title}</li>)}</ul>;
}

Pattern 4: Composition - Server Inside Client

模式4：组合 - Server Component嵌套在Client Component中

You CAN pass Server Components as children to Client Components:

typescript

// app/page.tsx (Server Component)
import ClientWrapper from './ClientWrapper';
import ServerContent from './ServerContent';

export default function Page() {
  return (
    <ClientWrapper>
      {/* Server Component as children */}
      <ServerContent />
    </ClientWrapper>
  );
}

// ClientWrapper.tsx (Client Component)
'use client';

import { useState } from 'react';

export default function ClientWrapper({
  children
}: {
  children: React.ReactNode
}) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(!isOpen)}>Toggle</button>
      {isOpen && children}
    </div>
  );
}

// ServerContent.tsx (Server Component)
export default async function ServerContent() {
  const data = await fetchData();
  return <div>{data.content}</div>;
}

可以将Server Component作为子组件传递给Client Component：

typescript

// app/page.tsx (Server Component)
import ClientWrapper from './ClientWrapper';
import ServerContent from './ServerContent';

export default function Page() {
  return (
    <ClientWrapper>
      {/* Server Component作为子组件 */}
      <ServerContent />
    </ClientWrapper>
  );
}

// ClientWrapper.tsx (Client Component)
'use client';

import { useState } from 'react';

export default function ClientWrapper({
  children
}: {
  children: React.ReactNode
}) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(!isOpen)}>切换</button>
      {isOpen && children}
    </div>
  );
}

// ServerContent.tsx (Server Component)
export default async function ServerContent() {
  const data = await fetchData();
  return <div>{data.content}</div>;
}

Anti-Patterns to Avoid

需要避免的反模式

Anti-Pattern 1: Using 'use client' Everywhere

反模式1：到处使用'use client'

Wrong:

typescript

// app/components/Header.tsx
'use client';  // Unnecessary!

export default function Header() {
  return <header><h1>My App</h1></header>;
}

Correct:

typescript

// app/components/Header.tsx
// No directive needed - keep it as Server Component
export default function Header() {
  return <header><h1>My App</h1></header>;
}

Why: Only use

'use client'

when you actually need client-side features. Static components should remain Server Components to reduce bundle size.

错误示例：

typescript

// app/components/Header.tsx
'use client';  // 不必要！

export default function Header() {
  return <header><h1>我的应用</h1></header>;
}

正确示例：

typescript

// app/components/Header.tsx
// 无需指令 - 保持为Server Component
export default function Header() {
  return <header><h1>我的应用</h1></header>;
}

原因： 仅在实际需要客户端特性时使用

'use client'

。静态组件应保持为Server Component以减少包体积。

Anti-Pattern 2: Fetching Data in Client Components

反模式2：在Client Component中获取数据

Wrong:

typescript

'use client';

import { useState, useEffect } from 'react';

export default function Products() {
  const [products, setProducts] = useState([]);

  useEffect(() => {
    fetch('/api/products')
      .then(r => r.json())
      .then(setProducts);
  }, []);

  return <div>{products.map(p => <div key={p.id}>{p.name}</div>)}</div>;
}

Correct:

typescript

// Server Component - no 'use client'
export default async function Products() {
  const response = await fetch('https://api.example.com/products');
  const products = await response.json();

  return <div>{products.map(p => <div key={p.id}>{p.name}</div>)}</div>;
}

Why: Server Components can fetch data directly, eliminating loading states and reducing client-side JavaScript.

错误示例：

typescript

'use client';

import { useState, useEffect } from 'react';

export default function Products() {
  const [products, setProducts] = useState([]);

  useEffect(() => {
    fetch('/api/products')
      .then(r => r.json())
      .then(setProducts);
  }, []);

  return <div>{products.map(p => <div key={p.id}>{p.name}</div>)}</div>;
}

正确示例：

typescript

// Server Component - 无需'use client'
export default async function Products() {
  const response = await fetch('https://api.example.com/products');
  const products = await response.json();

  return <div>{products.map(p => <div key={p.id}>{p.name}</div>)}</div>;
}

原因： Server Component可以直接获取数据，消除加载状态并减少客户端JavaScript。

Anti-Pattern 3: Accessing Server APIs in Client Components

反模式3：在Client Component中访问服务器API

Wrong:

typescript

'use client';

import { cookies } from 'next/headers'; // ERROR!

export default function ClientComponent() {
  const cookieStore = cookies(); // This will fail
  return <div>...</div>;
}

Correct:

typescript

// Server Component
import { cookies } from 'next/headers';
import ClientComponent from './ClientComponent';

export default async function ServerComponent() {
  const cookieStore = await cookies();
  const token = cookieStore.get('token')?.value;

  return <ClientComponent token={token} />;
}

Why:

cookies()

headers()

, and other server-only APIs can only be used in Server Components.

错误示例：

typescript

'use client';

import { cookies } from 'next/headers'; // 错误！

export default function ClientComponent() {
  const cookieStore = cookies(); // 会失败
  return <div>...</div>;
}

正确示例：

typescript

// Server Component
import { cookies } from 'next/headers';
import ClientComponent from './ClientComponent';

export default async function ServerComponent() {
  const cookieStore = await cookies();
  const token = cookieStore.get('token')?.value;

  return <ClientComponent token={token} />;
}

原因：

cookies()

、

headers()

等服务器专属API仅能在Server Component中使用。

Anti-Pattern 4: Serial Await (Waterfall)

反模式4：串行等待（瀑布流）

Wrong:

typescript

export default async function Page() {
  const user = await fetchUser();
  const posts = await fetchPosts();  // Waits for user to finish
  const comments = await fetchComments();  // Waits for posts to finish

  return <div>...</div>;
}

Correct:

typescript

export default async function Page() {
  // Fetch in parallel
  const [user, posts, comments] = await Promise.all([
    fetchUser(),
    fetchPosts(),
    fetchComments(),
  ]);

  return <div>...</div>;
}

Why: Parallel fetching reduces total load time significantly.

错误示例：

typescript

export default async function Page() {
  const user = await fetchUser();
  const posts = await fetchPosts();  // 等待user请求完成
  const comments = await fetchComments();  // 等待posts请求完成

  return <div>...</div>;
}

正确示例：

typescript

export default async function Page() {
  // 并行获取
  const [user, posts, comments] = await Promise.all([
    fetchUser(),
    fetchPosts(),
    fetchComments(),
  ]);

  return <div>...</div>;
}

原因： 并行获取可显著减少总加载时间。

Anti-Pattern 5: Importing Server Component into Client Component

反模式5：将Server Component导入到Client Component中

Wrong:

typescript

// ClientComponent.tsx
'use client';

import ServerComponent from './ServerComponent'; // This makes it a Client Component!

export default function ClientComponent() {
  return <div><ServerComponent /></div>;
}

Correct:

typescript

// ParentServerComponent.tsx (Server Component)
import ClientComponent from './ClientComponent';
import ServerComponent from './ServerComponent';

export default function ParentServerComponent() {
  return (
    <ClientComponent>
      <ServerComponent />
    </ClientComponent>
  );
}

Why: Importing a Server Component into a Client Component converts it to a Client Component. Pass it as children instead.

错误示例：

typescript

// ClientComponent.tsx
'use client';

import ServerComponent from './ServerComponent'; // 这会将其变为Client Component！

export default function ClientComponent() {
  return <div><ServerComponent /></div>;
}

正确示例：

typescript

// ParentServerComponent.tsx (Server Component)
import ClientComponent from './ClientComponent';
import ServerComponent from './ServerComponent';

export default function ParentServerComponent() {
  return (
    <ClientComponent>
      <ServerComponent />
    </ClientComponent>
  );
}

原因： 将Server Component导入到Client Component中会将其转换为Client Component。应改为通过子组件传递。

When Client Components ARE Appropriate

适合使用Client Components的场景

Client Components are the correct choice for:

Client Components适用于以下场景：

1. Interactive Forms

1. 交互式表单

typescript

'use client';

import { useState } from 'react';

export default function ContactForm() {
  const [email, setEmail] = useState('');

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    // Handle submission
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={email}
        onChange={(e) => setEmail(e.target.value)}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

typescript

'use client';

import { useState } from 'react';

export default function ContactForm() {
  const [email, setEmail] = useState('');

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    // 处理提交
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={email}
        onChange={(e) => setEmail(e.target.value)}
      />
      <button type="submit">提交</button>
    </form>
  );
}

2. Real-Time Features

2. 实时功能

typescript

'use client';

import { useEffect, useState } from 'react';

export default function LiveChat() {
  const [messages, setMessages] = useState([]);

  useEffect(() => {
    const ws = new WebSocket('wss://chat.example.com');
    ws.onmessage = (event) => {
      setMessages(prev => [...prev, event.data]);
    };
    return () => ws.close();
  }, []);

  return <div>{messages.map((m, i) => <div key={i}>{m}</div>)}</div>;
}

typescript

'use client';

import { useEffect, useState } from 'react';

export default function LiveChat() {
  const [messages, setMessages] = useState([]);

  useEffect(() => {
    const ws = new WebSocket('wss://chat.example.com');
    ws.onmessage = (event) => {
      setMessages(prev => [...prev, event.data]);
    };
    return () => ws.close();
  }, []);

  return <div>{messages.map((m, i) => <div key={i}>{m}</div>)}</div>;
}

3. Browser-Only Features

3. 浏览器专属功能

typescript

'use client';

import { useState, useEffect } from 'react';

export default function GeolocationDisplay() {
  const [location, setLocation] = useState(null);

  useEffect(() => {
    navigator.geolocation.getCurrentPosition((pos) => {
      setLocation({
        lat: pos.coords.latitude,
        lng: pos.coords.longitude,
      });
    });
  }, []);

  return location ? <div>Lat: {location.lat}, Lng: {location.lng}</div> : null;
}

typescript

'use client';

import { useState, useEffect } from 'react';

export default function GeolocationDisplay() {
  const [location, setLocation] = useState(null);

  useEffect(() => {
    navigator.geolocation.getCurrentPosition((pos) => {
      setLocation({
        lat: pos.coords.latitude,
        lng: pos.coords.longitude,
      });
    });
  }, []);

  return location ? <div>纬度：{location.lat}，经度：{location.lng}</div> : null;
}

4. Third-Party Libraries Requiring Window

4. 需要Window对象的第三方库

typescript

'use client';

import { useEffect, useState } from 'react';
import confetti from 'canvas-confetti';

export default function CelebrationButton() {
  const handleClick = () => {
    confetti();
  };

  return <button onClick={handleClick}>Celebrate!</button>;
}

typescript

'use client';

import { useEffect, useState } from 'react';
import confetti from 'canvas-confetti';

export default function CelebrationButton() {
  const handleClick = () => {
    confetti();
  };

  return <button onClick={handleClick}>庆祝！</button>;
}

5. React Context Providers

5. React Context提供者

typescript

'use client';

import { createContext, useState } from 'react';

export const ThemeContext = createContext();

export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light');

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

typescript

'use client';

import { createContext, useState } from 'react';

export const ThemeContext = createContext();

export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light');

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

Quick Decision Tree

快速决策树

Need interactivity? (onClick, onChange, etc.)
├─ Yes → Client Component ('use client')
└─ No → Continue...

Need React hooks? (useState, useEffect, etc.)
├─ Yes → Client Component ('use client')
└─ No → Continue...

Need browser APIs? (window, localStorage, etc.)
├─ Yes → Client Component ('use client')
└─ No → Continue...

Need to fetch data?
├─ Yes → Server Component (default)
└─ No → Continue...

Need cookies/headers/searchParams?
├─ Yes → Server Component (default)
└─ No → Server Component (default, unless specific need)

需要交互吗？（onClick、onChange等）
├─ 是 → Client Component（使用'use client'）
└─ 否 → 继续...

需要React钩子吗？（useState、useEffect等）
├─ 是 → Client Component（使用'use client'）
└─ 否 → 继续...

需要浏览器API吗？（window、localStorage等）
├─ 是 → Client Component（使用'use client'）
└─ 否 → 继续...

需要获取数据吗？
├─ 是 → Server Component（默认）
└─ 否 → 继续...

需要cookies/headers/searchParams吗？
├─ 是 → Server Component（默认）
└─ 否 → Server Component（默认，除非有特定需求）

Testing Component Type

测试组件类型

To verify component type:

typescript

// This works = Server Component
export default async function MyComponent() { ... }

// This works = Server Component
import { cookies } from 'next/headers';

// This works = Client Component
'use client';
import { useState } from 'react';

// This fails = Wrong combination
'use client';
import { cookies } from 'next/headers'; // ERROR!

验证组件类型：

typescript

// 可以运行 = Server Component
export default async function MyComponent() { ... }

// 可以运行 = Server Component
import { cookies } from 'next/headers';

// 可以运行 = Client Component
'use client';
import { useState } from 'react';

// 会失败 = 错误组合
'use client';
import { cookies } from 'next/headers'; // 错误！

Summary

总结

Default to Server Components - they're faster and more secure
Use Client Components only when you need interactivity or browser APIs
Never fetch data in Client Components with useEffect - use Server Components
Pass promises to Client Components with React 'use' API
Access cookies/headers/searchParams only in Server Components
Use composition pattern to mix Server and Client Components
Fetch in parallel with Promise.all to avoid waterfalls

默认使用Server Components - 它们更快、更安全
仅在需要交互或浏览器API时使用Client Components
永远不要在Client Component中使用useEffect获取数据 - 使用Server Components
通过React 'use' API向Client Components传递Promise
仅在Server Components中访问cookies/headers/searchParams
使用组合模式混合Server和Client Components
使用Promise.all并行获取数据以避免瀑布流

nextjs-server-client-components

Original

Translation

Next.js Server Components vs Client Components

Next.js Server Components 与 Client Components 对比

Overview

概述

TypeScript: NEVER Use any Type

TypeScript: 绝对不要使用any类型

Common Next.js Type Patterns

常见Next.js类型模式

When to Use This Skill

何时使用本指南

Core Decision: Server vs Client Components

核心决策：Server vs Client Components

Default: Server Components

默认选择：Server Components

Client Components: 'use client'

Client Components：使用'use client'指令

⚠️ CRITICAL: Server Components NEVER Need 'use client'

⚠️ 关键注意：Server Components永远不需要'use client'

Server Component Patterns

Server Component模式

Accessing Cookies

访问Cookies

Accessing Headers

访问Headers

Using searchParams

使用searchParams

Using pathname and Route Information

使用pathname和路由信息

⚠️ CRITICAL: useSearchParams ALWAYS Requires Suspense

⚠️ 关键注意：useSearchParams始终需要Suspense

React 'use' API for Promise Unwrapping

用于解包Promise的React 'use' API

Using 'use' with Promises

结合Promise使用'use'

Benefits of 'use' API

'use' API的优势

Using 'use' with Context

结合Context使用'use'

Common Patterns

常见模式

Pattern 1: Server Component Fetches, Client Component Interacts

模式1：Server Component获取数据，Client Component处理交互

Pattern 2: Parallel Data Fetching

模式2：并行数据获取

Pattern 3: Streaming with Suspense

模式3：结合Suspense的流式渲染

Pattern 4: Composition - Server Inside Client

模式4：组合 - Server Component嵌套在Client Component中

Anti-Patterns to Avoid

需要避免的反模式

Anti-Pattern 1: Using 'use client' Everywhere

反模式1：到处使用'use client'

Anti-Pattern 2: Fetching Data in Client Components

反模式2：在Client Component中获取数据

Anti-Pattern 3: Accessing Server APIs in Client Components

反模式3：在Client Component中访问服务器API

Anti-Pattern 4: Serial Await (Waterfall)

反模式4：串行等待（瀑布流）

Anti-Pattern 5: Importing Server Component into Client Component

反模式5：将Server Component导入到Client Component中

When Client Components ARE Appropriate

适合使用Client Components的场景

1. Interactive Forms

1. 交互式表单

2. Real-Time Features

2. 实时功能

3. Browser-Only Features

3. 浏览器专属功能

4. Third-Party Libraries Requiring Window

4. 需要Window对象的第三方库

5. React Context Providers

5. React Context提供者

Quick Decision Tree

快速决策树

Testing Component Type

测试组件类型

Summary

TypeScript: NEVER Use
`any`
Type

TypeScript: 绝对不要使用
`any`
类型