Next.js服务器组件Skill nextjs-server-components

---

名称：nextjs-server-components 用户可调用：false 描述：使用Next.js Server Components以实现最佳性能。在构建数据密集型Next.js应用程序时使用。 允许的工具：

• Bash
• Read

---

Next.js Server Components

掌握Next.js中的Server Components，以构建具有服务器端渲染和数据获取的高性能应用程序。

Server Components基础

在Next.js App Router中，所有组件默认都是Server Components：

// app/posts/page.tsx（默认Server Component）
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600 } // 缓存1小时
  });
  if (!res.ok) throw new Error('获取帖子失败');
  return res.json();
}

export default async function Posts() {
  const posts = await getPosts();

  return (
    <div>
      <h1>博客帖子</h1>
      {posts.map((post: Post) => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.content}</p>
          <span>{new Date(post.date).toLocaleDateString()}</span>
        </article>
      ))}
    </div>
  );
}

// 直接数据库访问（仅服务器）
import { db } from '@/lib/db';

export default async function Users() {
  const users = await db.user.findMany({
    select: {
      id: true,
      name: true,
      email: true
    }
  });

  return (
    <div>
      {users.map(user => (
        <div key={user.id}>
          {user.name} - {user.email}
        </div>
      ))}
    </div>
  );
}

Server vs Client Components决策树

// 使用Server Components时：
// - 获取数据
// - 直接访问后端资源
// - 在服务器上保留敏感信息
// - 在服务器上保留大型依赖项

// Server Component（默认）
export default async function ServerComp() {
  const data = await fetchData();
  return <div>{data}</div>;
}

// 使用Client Components时：
// - 使用交互性（onClick、onChange等）
// - 使用状态或生命周期钩子（useState、useEffect）
// - 使用仅浏览器API（localStorage、window等）
// - 使用依赖于状态/效果的自定义钩子
// - 使用React Context

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

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

  return (
    <button onClick={() => setCount(count + 1)}>
      计数：{count}
    </button>
  );
}

// 组合：Server Component与Client Component
export default async function Page() {
  const data = await fetchData(); // 服务器端

  return (
    <div>
      <ServerContent data={data} />
      <InteractiveButton /> {/* Client Component */}
    </div>
  );
}

用于变异的Server Actions

// app/actions.ts - Server Actions
'use server';

import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string;
  const content = formData.get('content') as string;

  const post = await db.post.create({
    data: { title, content }
  });

  revalidatePath('/posts');
  redirect(`/posts/${post.id}`);
}

export async function updatePost(id: string, formData: FormData) {
  const title = formData.get('title') as string;
  const content = formData.get('content') as string;

  await db.post.update({
    where: { id },
    data: { title, content }
  });

  revalidatePath(`/posts/${id}`);
  return { success: true };
}

export async function deletePost(id: string) {
  await db.post.delete({ where: { id } });
  revalidatePath('/posts');
}

// app/posts/new/page.tsx - 使用Server Actions
export default function NewPost() {
  return (
    <form action={createPost}>
      <input name="title" placeholder="标题" required />
      <textarea name="content" placeholder="内容" required />
      <button type="submit">创建帖子</button>
    </form>
  );
}

// 客户端增强
'use client';
import { useFormStatus, useFormState } from 'react-dom';
import { createPost } from './actions';

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? '创建中...' : '创建帖子'}
    </button>
  );
}

export default function NewPostForm() {
  const [state, formAction] = useFormState(createPost, null);

  return (
    <form action={formAction}>
      <input name="title" required />
      <textarea name="content" required />
      {state?.error && <p className="error">{state.error}</p>}
      <SubmitButton />
    </form>
  );
}

数据获取模式

// 并行数据获取
async function getUser(id: string) {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

async function getUserPosts(id: string) {
  const res = await fetch(`/api/users/${id}/posts`);
  return res.json();
}

export default async function UserProfile({ params }: {
  params: { id: string }
}) {
  // 并行获取
  const [user, posts] = await Promise.all([
    getUser(params.id),
    getUserPosts(params.id)
  ]);

  return (
    <div>
      <UserInfo user={user} />
      <UserPosts posts={posts} />
    </div>
  );
}

// 顺序数据获取（需要时）
export default async function Dashboard() {
  // 先获取用户
  const user = await getUser();

  // 然后获取用户特定数据
  const settings = await getUserSettings(user.id);
  const notifications = await getUserNotifications(user.id);

  return (
    <div>
      <UserHeader user={user} settings={settings} />
      <Notifications items={notifications} />
    </div>
  );
}

// 使用Suspense优化瀑布流
import { Suspense } from 'react';

export default function Page() {
  return (
    <div>
      {/* 用户先加载 */}
      <Suspense fallback={<UserSkeleton />}>
        <User />
      </Suspense>

      {/* 这些并行加载 */}
      <div className="grid">
        <Suspense fallback={<SettingsSkeleton />}>
          <Settings />
        </Suspense>
        <Suspense fallback={<NotificationsSkeleton />}>
          <Notifications />
        </Suspense>
      </div>
    </div>
  );
}

使用Suspense流式传输

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

export default function Dashboard() {
  return (
    <div>
      <h1>仪表板</h1>

      {/* 快速组件立即渲染 */}
      <QuickStats />

      {/* 慢组件流式传输 */}
      <Suspense fallback={<ChartSkeleton />}>
        <RevenueChart />
      </Suspense>

      <Suspense fallback={<TableSkeleton />}>
        <RecentOrders />
      </Suspense>

      <Suspense fallback={<ActivitySkeleton />}>
        <ActivityFeed />
      </Suspense>
    </div>
  );
}

async function RevenueChart() {
  // 慢数据获取
  const data = await fetchRevenueData();

  return <Chart data={data} />;
}

async function RecentOrders() {
  const orders = await fetchOrders({ limit: 10 });

  return (
    <table>
      {orders.map(order => (
        <tr key={order.id}>
          <td>{order.id}</td>
          <td>{order.total}</td>
        </tr>
      ))}
    </table>
  );
}

// 嵌套Suspense以进行细粒度流式传输
async function ActivityFeed() {
  return (
    <div>
      <h2>活动</h2>
      <Suspense fallback={<div>加载评论中...</div>}>
        <Comments />
      </Suspense>
      <Suspense fallback={<div>加载点赞中...</div>}>
        <Likes />
      </Suspense>
    </div>
  );
}

Server Component模式

// 模式1：Server Component中的数据获取
async function fetchProduct(id: string) {
  const product = await db.product.findUnique({ where: { id } });
  return product;
}

export default async function ProductPage({ params }: {
  params: { id: string }
}) {
  const product = await fetchProduct(params.id);

  return (
    <div>
      <ProductDetails product={product} />
      <AddToCartButton productId={product.id} /> {/* Client Component */}
    </div>
  );
}

// 模式2：Server Component作为数据提供者
async function ProductWithReviews({ id }: { id: string }) {
  const [product, reviews] = await Promise.all([
    fetchProduct(id),
    fetchReviews(id)
  ]);

  return (
    <>
      <ProductInfo product={product} />
      <ReviewList reviews={reviews} />
      <ReviewForm productId={id} /> {/* Client Component */}
    </>
  );
}

// 模式3：组合Server和Client Components
export default async function Page() {
  const data = await fetchData();

  return (
    <ClientWrapper>
      {/* Server Component子组件在Client Components内工作 */}
      <ServerContent data={data} />
    </ClientWrapper>
  );
}

// 模式4：从Server到Client传递Props
export default async function Layout({
  children
}: {
  children: React.ReactNode
}) {
  const user = await getUser();

  return (
    <div>
      <ClientHeader user={user} /> {/* 将服务器数据传递给客户端 */}
      <main>{children}</main>
    </div>
  );
}

Client Component模式

// 模式1：最小化Client Component
'use client';
import { useState } from 'react';

export function Counter({ initialCount = 0 }: { initialCount?: number }) {
  const [count, setCount] = useState(initialCount);

  return (
    <button onClick={() => setCount(count + 1)}>
      计数：{count}
    </button>
  );
}

// 模式2：带有Server Component子组件的Client Component
'use client';
import { useState } from 'react';

export function Tabs({ children }: { children: React.ReactNode }) {
  const [activeTab, setActiveTab] = useState(0);

  return (
    <div>
      <div className="tabs">
        <button onClick={() => setActiveTab(0)}>标签1</button>
        <button onClick={() => setActiveTab(1)}>标签2</button>
      </div>
      <div>{children}</div>
    </div>
  );
}

// 使用：Server Component子组件有效
export default async function Page() {
  const data = await fetchData();

  return (
    <Tabs>
      <ServerContent data={data} />
    </Tabs>
  );
}

// 模式3：带有上下文的Client包装器
'use client';
import { createContext, useContext, useState } from 'react';

const ThemeContext = createContext<{
  theme: string;
  setTheme: (theme: string) => void;
} | null>(null);

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

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

// 模式4：使用Server Actions进行乐观更新
'use client';
import { useOptimistic } from 'react';
import { addTodo } from './actions';

export function TodoList({ todos }: { todos: Todo[] }) {
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    (state, newTodo: string) => [
      ...state,
      { id: Date.now(), text: newTodo, pending: true }
    ]
  );

  async function formAction(formData: FormData) {
    const text = formData.get('text') as string;
    addOptimisticTodo(text);
    await addTodo(text);
  }

  return (
    <div>
      {optimisticTodos.map(todo => (
        <div key={todo.id} style={{ opacity: todo.pending ? 0.5 : 1 }}>
          {todo.text}
        </div>
      ))}
      <form action={formAction}>
        <input name="text" />
        <button type="submit">添加</button>
      </form>
    </div>
  );
}

组合策略

// 策略1：Server Component作为布局
export default async function Layout({
  children
}: {
  children: React.ReactNode
}) {
  const user = await getUser();

  return (
    <div>
      <ServerNav user={user} />
      <Sidebar>
        <ClientSidebarContent /> {/* 交互式侧边栏 */}
      </Sidebar>
      <main>{children}</main>
    </div>
  );
}

// 策略2：将Server Components作为Props传递
export default async function Page() {
  const posts = await getPosts();

  return (
    <ClientLayout
      sidebar={<ServerSidebar posts={posts} />}
      main={<ServerContent posts={posts} />}
    />
  );
}

// 策略3：带有多个Client Components的Server Component
export default async function Dashboard() {
  const data = await fetchDashboardData();

  return (
    <div>
      <ClientHeader />
      <ServerStats data={data.stats} />
      <ClientChart data={data.chartData} />
      <ServerTable data={data.tableData} />
      <ClientFilters />
    </div>
  );
}

// 策略4：条件性Client Components
export default async function Page() {
  const user = await getUser();

  return (
    <div>
      {user.isAdmin ? (
        <AdminClientPanel />
      ) : (
        <UserServerContent user={user} />
      )}
    </div>
  );
}

仅服务器代码

// lib/server-only-utils.ts
import 'server-only'; // 确保此文件从不捆绑到客户端

export async function getSecretData() {
  const apiKey = process.env.SECRET_API_KEY;
  // 此代码仅在服务器上运行
  const res = await fetch('https://api.example.com/secret', {
    headers: {
      Authorization: `Bearer ${apiKey}`
    }
  });
  return res.json();
}

export function decryptData(encrypted: string) {
  // 加密逻辑，从不传送到客户端
  return decrypt(encrypted, process.env.ENCRYPTION_KEY);
}

// app/dashboard/page.tsx
import { getSecretData } from '@/lib/server-only-utils';

export default async function Dashboard() {
  const data = await getSecretData();

  return <div>{data.publicInfo}</div>;
}

// 类型安全的环境变量
// env.ts
import 'server-only';

export const env = {
  DATABASE_URL: process.env.DATABASE_URL!,
  API_KEY: process.env.API_KEY!,
  SECRET_KEY: process.env.SECRET_KEY!
} as const;

// 在Server Components中使用
import { env } from '@/lib/env';

export default async function Page() {
  const data = await fetch('https://api.example.com', {
    headers: { 'X-API-Key': env.API_KEY }
  });

  return <div>数据已获取</div>;
}

性能影响

// 重依赖仅加载在服务器上
import { marked } from 'marked'; // Markdown解析器（大型库）

export default async function MarkdownPage({ content }: {
  content: string
}) {
  // 这仅在服务器上运行，保持捆绑包小
  const html = marked(content);

  return <div dangerouslySetInnerHTML={{ __html: html }} />;
}

// 服务器上的图像优化
import sharp from 'sharp'; // 图像处理库

export default async function OptimizedImage({ src }: { src: string }) {
  // 在服务器上处理
  const buffer = await fetch(src).then(r => r.arrayBuffer());
  const optimized = await sharp(buffer)
    .resize(800, 600)
    .webp()
    .toBuffer();

  const base64 = optimized.toString('base64');

  return <img src={`data:image/webp;base64,${base64}`} />;
}

// 服务器上的计算密集型操作
export default async function AnalyticsPage() {
  // 重计算在服务器上运行
  const rawData = await fetchRawData();
  const processed = processLargeDataset(rawData); // CPU密集型
  const stats = calculateStatistics(processed); // 更多计算

  return <StatsDisplay stats={stats} />;
}

// 多个数据源聚合
export default async function AggregatedDashboard() {
  const [analytics, sales, inventory] = await Promise.all([
    fetchAnalytics(),
    fetchSales(),
    fetchInventory()
  ]);

  const report = generateReport(analytics, sales, inventory);

  return <ReportView report={report} />;
}

Server Components中的错误处理

// 在Server Components中抛出错误
export default async function PostPage({ params }: {
  params: { id: string }
}) {
  const post = await db.post.findUnique({
    where: { id: params.id }
  });

  if (!post) {
    throw new Error('帖子未找到');
  }

  return <Article post={post} />;
}

// 使用notFound()处理404
import { notFound } from 'next/navigation';

export default async function UserPage({ params }: {
  params: { id: string }
}) {
  const user = await db.user.findUnique({
    where: { id: params.id }
  });

  if (!user) {
    notFound(); // 渲染not-found.tsx
  }

  return <UserProfile user={user} />;
}

// 使用try-catch处理错误
export default async function Page() {
  try {
    const data = await fetchData();
    return <Content data={data} />;
  } catch (error) {
    console.error('获取数据失败：', error);
    return <ErrorMessage />;
  }
}

// Server Components的错误边界
// 由最近的error.tsx捕获
export default async function RiskyComponent() {
  const data = await riskyOperation(); // 可能抛出

  return <Display data={data} />;
}

何时使用此技能

使用nextjs-server-components时你需要：

• 在服务器上获取数据
• 直接访问后端资源
• 在服务器端保留敏感数据
• 减少客户端捆绑包大小
• 改善初始页面加载
• 构建SEO优化的页面
• 流式传输内容到客户端
• 实现零JS页面
• 为性能优化
• 直接访问数据库
• 使用仅服务器库
• 执行重计算

最佳实践

1. 默认使用server components - 仅在需要交互性、状态或浏览器API时添加’use client’。

2. 数据获取靠近使用处 - 将数据获取与使用数据的组件放在一起。

3. 利用并行数据获取 - 使用Promise.all同时获取独立数据源。

4. 使用流式传输以改善UX - 将慢组件包裹在Suspense中以显示加载内容。

5. 保持敏感逻辑在服务器端 - 数据库查询、API密钥和业务逻辑应留在服务器。

6. 最小化client components - 每个’use client’边界增加JavaScript捆绑包大小。

7. 适当缓存数据 - 基于数据新鲜度需求使用Next.js缓存策略（revalidate、no-store）。

8. 优雅处理错误 - 使用错误边界和not-found页面以更好处理错误。

9. 使用TypeScript以确保类型安全 - 定义正确的Props和数据类型以早期捕获错误。

10. 测试server component行为 - 在测试中验证数据获取、错误处理和渲染。

常见陷阱

1. 在server components中使用仅客户端API - window、localStorage、document在服务器上不可用。

2. 未正确处理异步错误 - 未处理的Promise拒绝导致整个页面崩溃。

3. 混合服务器和客户端状态 - 状态管理库在server components中无效。

4. 过度使用client components - 不必要地添加’use client’增加捆绑包大小并降低性能。

5. 未利用数据流式传输 - 缺少Suspense边界导致慢页面加载而非渐进渲染。

6. 忽略缓存策略 - 未设置revalidate时间导致陈旧数据或不必要请求。

7. 未优化数据获取 - 顺序获取导致瀑布流；尽可能使用并行获取。

8. 暴露敏感数据 - 意外将秘密或API密钥传递给client components。

9. 未处理加载状态 - 数据获取期间缺少加载UI导致糟糕用户体验。

10. 误解组件边界 - Server components不能直接导入到client components。

资源

• Next.js Server Components
• Client Components
• Composition Patterns
• Server Actions
• Data Fetching
• React Server Components