🚀 快速安装

复制以下命令并运行，立即安装此 Skill：

npx @anthropic-ai/skills install wshobson/agents/nextjs-app-router-patterns

💡 提示：需要 Node.js 和 NPM

Next.js 应用程序路由器模式

针对 Next.js 14+ 应用程序路由器架构、服务器组件和现代全栈 React 开发的综合模式。

何时使用此技能

  • 使用应用程序路由器构建新的 Next.js 应用
  • 从页面路由器迁移到应用程序路由器
  • 实现服务器组件和流式渲染
  • 设置并行和拦截路由
  • 优化数据获取和缓存
  • 使用服务器操作构建全栈功能

核心概念

1. 渲染模式

模式 位置 何时使用
服务器组件 仅服务器 数据获取、繁重计算、密钥
客户端组件 浏览器 交互性、钩子、浏览器应用程序编程接口
静态 构建时 很少变化的内容
动态 请求时 个性化或实时数据
流式渲染 渐进式 大型页面、慢速数据源

2. 文件约定

app/
├── layout.tsx       # 共享的 UI 包装器
├── page.tsx         # 路由 UI
├── loading.tsx      # 加载 UI (Suspense)
├── error.tsx        # 错误边界
├── not-found.tsx    # 404 UI
├── route.ts         # 应用程序编程接口端点
├── template.tsx     # 重新挂载的布局
├── default.tsx      # 并行路由回退
└── opengraph-image.tsx  # 开放图谱图片生成

快速开始

// app/layout.tsx
import { Inter } from 'next/font/google'
import { Providers } from './providers'

const inter = Inter({ subsets: ['latin'] })

export const metadata = {
  title: { default: '我的应用', template: '%s | 我的应用' },
  description: '使用 Next.js App Router 构建',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className={inter.className}>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

// app/page.tsx - 默认是服务器组件
async function getProducts() {
  const res = await fetch('https://api.example.com/products', {
    next: { revalidate: 3600 }, // ISR：每小时重新验证
  })
  return res.json()
}

export default async function HomePage() {
  const products = await getProducts()

  return (
    <main>
      <h1>产品</h1>
      <ProductGrid products={products} />
    </main>
  )
}

模式

模式 1：带数据获取的服务器组件

// app/products/page.tsx
import { Suspense } from 'react'
import { ProductList, ProductListSkeleton } from '@/components/products'
import { FilterSidebar } from '@/components/filters'

interface SearchParams {
  category?: string
  sort?: 'price' | 'name' | 'date'
  page?: string
}

export default async function ProductsPage({
  searchParams,
}: {
  searchParams: Promise<SearchParams>
}) {
  const params = await searchParams

  return (
    <div className="flex gap-8">
      <FilterSidebar />
      <Suspense
        key={JSON.stringify(params)}
        fallback={<ProductListSkeleton />}
      >
        <ProductList
          category={params.category}
          sort={params.sort}
          page={Number(params.page) || 1}
        />
      </Suspense>
    </div>
  )
}

// components/products/ProductList.tsx - 服务器组件
async function getProducts(filters: ProductFilters) {
  const res = await fetch(
    `${process.env.API_URL}/products?${new URLSearchParams(filters)}`,
    { next: { tags: ['products'] } }
  )
  if (!res.ok) throw new Error('获取产品失败')
  return res.json()
}

export async function ProductList({ category, sort, page }: ProductFilters) {
  const { products, totalPages } = await getProducts({ category, sort, page })

  return (
    <div>
      <div className="grid grid-cols-3 gap-4">
        {products.map((product) => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
      <Pagination currentPage={page} totalPages={totalPages} />
    </div>
  )
}

模式 2：使用 ‘use client’ 的客户端组件

// components/products/AddToCartButton.tsx
'use client'

import { useState, useTransition } from 'react'
import { addToCart } from '@/app/actions/cart'

export function AddToCartButton({ productId }: { productId: string }) {
  const [isPending, startTransition] = useTransition()
  const [error, setError] = useState<string | null>(null)

  const handleClick = () => {
    setError(null)
    startTransition(async () => {
      const result = await addToCart(productId)
      if (result.error) {
        setError(result.error)
      }
    })
  }

  return (
    <div>
      <button
        onClick={handleClick}
        disabled={isPending}
        className="btn-primary"
      >
        {isPending ? '添加中...' : '加入购物车'}
      </button>
      {error && <p className="text-red-500 text-sm">{error}</p>}
    </div>
  )
}

模式 3：服务器操作

// app/actions/cart.ts
"use server";

import { revalidateTag } from "next/cache";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";

export async function addToCart(productId: string) {
  const cookieStore = await cookies();
  const sessionId = cookieStore.get("session")?.value;

  if (!sessionId) {
    redirect("/login");
  }

  try {
    await db.cart.upsert({
      where: { sessionId_productId: { sessionId, productId } },
      update: { quantity: { increment: 1 } },
      create: { sessionId, productId, quantity: 1 },
    });

    revalidateTag("cart");
    return { success: true };
  } catch (error) {
    return { error: "无法将商品加入购物车" };
  }
}

export async function checkout(formData: FormData) {
  const address = formData.get("address") as string;
  const payment = formData.get("payment") as string;

  // 验证
  if (!address || !payment) {
    return { error: "缺少必填字段" };
  }

  // 处理订单
  const order = await processOrder({ address, payment });

  // 重定向到确认页
  redirect(`/orders/${order.id}/confirmation`);
}

模式 4：并行路由

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
  analytics,
  team,
}: {
  children: React.ReactNode
  analytics: React.ReactNode
  team: React.ReactNode
}) {
  return (
    <div className="dashboard-grid">
      <main>{children}</main>
      <aside className="analytics-panel">{analytics}</aside>
      <aside className="team-panel">{team}</aside>
    </div>
  )
}

// app/dashboard/@analytics/page.tsx
export default async function AnalyticsSlot() {
  const stats = await getAnalytics()
  return <AnalyticsChart data={stats} />
}

// app/dashboard/@analytics/loading.tsx
export default function AnalyticsLoading() {
  return <ChartSkeleton />
}

// app/dashboard/@team/page.tsx
export default async function TeamSlot() {
  const members = await getTeamMembers()
  return <TeamList members={members} />
}

模式 5：拦截路由（模态框模式）

// 照片模态框的文件结构
// app/
// ├── @modal/
// │   ├── (.)photos/[id]/page.tsx  # 拦截
// │   └── default.tsx
// ├── photos/
// │   └── [id]/page.tsx            # 完整页面
// └── layout.tsx

// app/@modal/(.)photos/[id]/page.tsx
import { Modal } from '@/components/Modal'
import { PhotoDetail } from '@/components/PhotoDetail'

export default async function PhotoModal({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const photo = await getPhoto(id)

  return (
    <Modal>
      <PhotoDetail photo={photo} />
    </Modal>
  )
}

// app/photos/[id]/page.tsx - 完整页面版本
export default async function PhotoPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const photo = await getPhoto(id)

  return (
    <div className="photo-page">
      <PhotoDetail photo={photo} />
      <RelatedPhotos photoId={id} />
    </div>
  )
}

// app/layout.tsx
export default function RootLayout({
  children,
  modal,
}: {
  children: React.ReactNode
  modal: React.ReactNode
}) {
  return (
    <html>
      <body>
        {children}
        {modal}
      </body>
    </html>
  )
}

模式 6：使用 Suspense 流式渲染

// app/product/[id]/page.tsx
import { Suspense } from 'react'

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params

  // 此数据首先加载（阻塞）
  const product = await getProduct(id)

  return (
    <div>
      {/* 立即渲染 */}
      <ProductHeader product={product} />

      {/* 流式加载评论 */}
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews productId={id} />
      </Suspense>

      {/* 流式加载推荐 */}
      <Suspense fallback={<RecommendationsSkeleton />}>
        <Recommendations productId={id} />
      </Suspense>
    </div>
  )
}

// 这些组件自己获取数据
async function Reviews({ productId }: { productId: string }) {
  const reviews = await getReviews(productId) // 慢速应用程序编程接口
  return <ReviewList reviews={reviews} />
}

async function Recommendations({ productId }: { productId: string }) {
  const products = await getRecommendations(productId) // 基于机器学习，速度慢
  return <ProductCarousel products={products} />
}

模式 7：路由处理程序（应用程序编程接口路由）

// app/api/products/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const category = searchParams.get("category");

  const products = await db.product.findMany({
    where: category ? { category } : undefined,
    take: 20,
  });

  return NextResponse.json(products);
}

export async function POST(request: NextRequest) {
  const body = await request.json();

  const product = await db.product.create({
    data: body,
  });

  return NextResponse.json(product, { status: 201 });
}

// app/api/products/[id]/route.ts
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> },
) {
  const { id } = await params;
  const product = await db.product.findUnique({ where: { id } });

  if (!product) {
    return NextResponse.json({ error: "产品未找到" }, { status: 404 });
  }

  return NextResponse.json(product);
}

模式 8：元数据和搜索引擎优化

// app/products/[slug]/page.tsx
import { Metadata } from 'next'
import { notFound } from 'next/navigation'

type Props = {
  params: Promise<{ slug: string }>
}

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params
  const product = await getProduct(slug)

  if (!product) return {}

  return {
    title: product.name,
    description: product.description,
    openGraph: {
      title: product.name,
      description: product.description,
      images: [{ url: product.image, width: 1200, height: 630 }],
    },
    twitter: {
      card: 'summary_large_image',
      title: product.name,
      description: product.description,
      images: [product.image],
    },
  }
}

export async function generateStaticParams() {
  const products = await db.product.findMany({ select: { slug: true } })
  return products.map((p) => ({ slug: p.slug }))
}

export default async function ProductPage({ params }: Props) {
  const { slug } = await params
  const product = await getProduct(slug)

  if (!product) notFound()

  return <ProductDetail product={product} />
}

缓存策略

数据缓存

// 无缓存（始终最新）
fetch(url, { cache: "no-store" });

// 永久缓存（静态）
fetch(url, { cache: "force-cache" });

// ISR - 60 秒后重新验证
fetch(url, { next: { revalidate: 60 } });

// 基于标签的失效
fetch(url, { next: { tags: ["products"] } });

// 通过服务器操作失效
("use server");
import { revalidateTag, revalidatePath } from "next/cache";

export async function updateProduct(id: string, data: ProductData) {
  await db.product.update({ where: { id }, data });
  revalidateTag("products");
  revalidatePath("/products");
}

最佳实践

要做的

  • 从服务器组件开始 – 仅在需要时添加 ‘use client’
  • 将数据获取与使用处放在一起 – 在使用的组件中获取数据
  • 使用 Suspense 边界 – 为慢速数据启用流式渲染
  • 利用并行路由 – 独立的加载状态
  • 使用服务器操作 – 用于带有渐进增强的修改操作

不要做的

  • 不要传递不可序列化的数据 – 服务器 → 客户端边界限制
  • 不要在服务器组件中使用钩子 – 没有 useState、useEffect
  • 不要在客户端组件中获取数据 – 使用服务器组件或 React Query
  • 不要过度嵌套布局 – 每个布局都会增加组件树
  • 不要忽略加载状态 – 始终提供 loading.tsx 或 Suspense

📄 原始文档

完整文档（英文）：

https://skills.sh/wshobson/agents/nextjs-app-router-patterns

💡 提示：点击上方链接查看 skills.sh 原始英文文档，方便对照翻译。

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。