Next.js App Router 缓存与渲染架构深度指南

用户请求
  │
  ▼
┌─────────────────────────────────────────────────────┐
│  Middleware / Proxy                                  │
│  · 读写 cookies / headers                            │
│  · 重写 / 重定向 / 拦截                               │
│  · 不是安全边界，不能替代真正鉴权                      │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Full Route Cache 检查                               │
│  · 命中：直接返回缓存的 HTML + RSC Payload             │
│  · 未命中：进入渲染流程                               │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Route 渲染（Server Component Tree）                  │
│  ┌───────────────────────────────────────────────┐  │
│  │ Request Memoization                            │  │
│  │ · 同一渲染周期内相同 fetch 自动去重              │  │
│  └───────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────┐  │
│  │ Data Cache                                     │  │
│  │ · 跨请求持久化 fetch / cache 结果                │  │
│  │ · force-cache / no-store / revalidate 控制      │  │
│  └───────────────────────────────────────────────┘  │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Server → Client 边界                                │
│  · RSC Payload 序列化                                 │
│  · "use client" 组件的 props 必须可序列化              │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Hydration                                           │
│  · 客户端 React 接管 HTML，绑定事件                    │
│  · 服务端 HTML 必须与客户端首次渲染一致                 │
└─────────────────────────────────────────────────────┘

// layout.tsx 和 page.tsx 都调用同一个接口
// 同一轮服务端渲染里只会发出一次请求
async function getUser(id: string) {
  const res = await fetch(`https://api.example.com/users/${id}`);
  return res.json();
}

// 缓存 60 秒
const posts = await fetch("https://api.example.com/posts", {
  next: { revalidate: 60 },
});
 
// 永不缓存
const cart = await fetch("https://api.example.com/cart", {
  cache: "no-store",
});
 
// 打标签，支持按需失效
const products = await fetch("https://api.example.com/products", {
  next: { tags: ["products"] },
});

import { cookies } from "next/headers";
 
export default async function Page() {
  const cookieStore = await cookies();
  const theme = cookieStore.get("theme");
 
  return <div>Theme: {theme?.value}</div>;
}

// 即使子组件尝试使用动态行为，也强制静态
// 动态 API 在这种模式下可能会抛错或返回空值
export const dynamic = "force-static";

// app/blog/page.tsx
export const revalidate = 3600;
 
async function getPosts() {
  const res = await fetch("https://api.example.com/posts", {
    next: { revalidate: 3600 },
  });
 
  return res.json();
}
 
export default async function BlogPage() {
  const posts = await getPosts();
 
  return <PostList posts={posts} />;
}

// app/actions.ts
"use server";
 
import { revalidatePath, revalidateTag } from "next/cache";
 
export async function publishPost() {
  // 数据库操作...
 
  revalidatePath("/blog");
  revalidateTag("posts");
}

// app/api/revalidate/route.ts
import { revalidateTag } from "next/cache";
import { NextRequest } from "next/server";
 
export async function POST(request: NextRequest) {
  const { tag, secret } = await request.json();
 
  if (secret !== process.env.REVALIDATION_SECRET) {
    return Response.json({ message: "Invalid secret" }, { status: 401 });
  }
 
  revalidateTag(tag);
 
  return Response.json({ revalidated: true, now: Date.now() });
}

"use server";
 
import { z } from "zod";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { revalidateTag } from "next/cache";
 
const CreatePostSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().min(1),
});
 
export async function createPost(formData: FormData) {
  const cookieStore = await cookies();
  const session = cookieStore.get("session");
 
  if (!session) {
    redirect("/login");
  }
 
  const parsed = CreatePostSchema.safeParse({
    title: formData.get("title"),
    content: formData.get("content"),
  });
 
  if (!parsed.success) {
    return { error: parsed.error.flatten() };
  }
 
  const user = await getUserFromSession(session.value);
 
  if (!user || user.role !== "author") {
    return { error: "Unauthorized" };
  }
 
  await db.posts.create({ data: parsed.data });
  revalidateTag("posts");
}

// middleware.ts：只作为 UX 优化层
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
export function middleware(request: NextRequest) {
  const session = request.cookies.get("session");
 
  if (!session && request.nextUrl.pathname.startsWith("/dashboard")) {
    return NextResponse.redirect(new URL("/login", request.url));
  }
 
  return NextResponse.next();
}
 
export const config = {
  matcher: ["/dashboard/:path*", "/api/admin/:path*"],
};

Server Component（默认）
  │
  ├── Server Component ✅
  │
  ├── "use client" Component ← 模块边界
  │     │
  │     ├── import 进来的子组件也进入客户端 bundle
  │     │
  │     └── 但可以通过 children / slots 接收 Server Component
  │
  └── Server Component ✅

// ClientWrapper.tsx
"use client";
 
import { useState } from "react";
 
export function ClientWrapper({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
 
  return (
    <div>
      <button onClick={() => setOpen((current) => !current)}>Toggle</button>
      {open && children}
    </div>
  );
}

// page.tsx：Server Component
import { ClientWrapper } from "./ClientWrapper";
import { ServerContent } from "./ServerContent";
 
export default function Page() {
  return (
    <ClientWrapper>
      <ServerContent />
    </ClientWrapper>
  );
}

// 错误：传递了不可序列化的 prop
<ClientComponent
  onClick={() => console.log("hi")}
  user={new User("Alice")}
/>;

// 正确：传递 Server Action 或普通数据
<ClientComponent
  deleteAction={deletePost}
  user={{ id: "1", name: "Alice" }}
/>;

"use client";
 
import { useEffect, useState } from "react";
 
export function ClientOnlyComponent() {
  const [mounted, setMounted] = useState(false);
 
  useEffect(() => {
    setMounted(true);
  }, []);
 
  if (!mounted) {
    return <div className="skeleton" />;
  }
 
  return <div>Window width: {window.innerWidth}</div>;
}

<time dateTime={post.createdAt} suppressHydrationWarning>
  {formatDate(post.createdAt)}
</time>

// app/blog/page.tsx
export const revalidate = 60;
 
async function getPosts() {
  const res = await fetch("https://api.example.com/posts", {
    next: { tags: ["posts"], revalidate: 60 },
  });
 
  return res.json();
}
 
export default async function BlogPage() {
  const posts = await getPosts();
 
  return (
    <main>
      <h1>Blog</h1>
      <ul>
        {posts.map((post: { id: string; slug: string; title: string; publishedAt: string }) => (
          <li key={post.id}>
            <a href={`/blog/${post.slug}`}>{post.title}</a>
            <span>{post.publishedAt}</span>
          </li>
        ))}
      </ul>
    </main>
  );
}

// app/blog/actions.ts
"use server";
 
import { revalidateTag } from "next/cache";
 
export async function refreshBlog() {
  revalidateTag("posts");
}

// app/api/webhook/route.ts
import { revalidateTag } from "next/cache";
import { NextRequest } from "next/server";
 
export async function POST(request: NextRequest) {
  const authHeader = request.headers.get("authorization");
 
  if (authHeader !== `Bearer ${process.env.WEBHOOK_SECRET}`) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }
 
  const body = await request.json();
 
  if (body.event === "post.published" || body.event === "post.updated") {
    revalidateTag("posts");
    revalidateTag(`post-${body.data.slug}`);
  }
 
  return Response.json({
    revalidated: true,
    tags: ["posts", `post-${body.data.slug}`],
    now: Date.now(),
  });
}

// app/dashboard/page.tsx
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
 
async function getUserData(sessionToken: string) {
  const res = await fetch("https://api.example.com/me", {
    headers: { Authorization: `Bearer ${sessionToken}` },
    cache: "no-store",
  });
 
  if (!res.ok) return null;
 
  return res.json();
}
 
export default async function DashboardPage() {
  const cookieStore = await cookies();
  const session = cookieStore.get("session_token");
 
  if (!session) {
    redirect("/login");
  }
 
  const user = await getUserData(session.value);
 
  if (!user) {
    redirect("/login");
  }
 
  return (
    <main>
      <h1>Welcome, {user.name}</h1>
      <section>
        <h2>Your Stats</h2>
        <p>Posts: {user.postCount}</p>
        <p>Last login: {user.lastLogin}</p>
        <p>Server time: {new Date().toISOString()}</p>
      </section>
    </main>
  );
}

import { Suspense } from "react";
import { StaticHeader } from "./StaticHeader";
import { DynamicUserBanner } from "./DynamicUserBanner";
import { BannerSkeleton } from "./BannerSkeleton";
 
export default function Page() {
  return (
    <div>
      <StaticHeader />
      <Suspense fallback={<BannerSkeleton />}>
        <DynamicUserBanner />
      </Suspense>
    </div>
  );
}

页面是否需要用户个性化数据？
  │
  ├── 是 → 动态渲染
  │         cookies() / headers() + cache: "no-store"
  │         同时考虑 PPR 隔离个性化区域
  │
  └── 否 → 数据多久变一次？
              │
              ├── 几乎不变 → 纯静态 SSG
              │
              ├── 定期变化 → ISR
              │     ├── 可预测频率 → revalidate: N
              │     └── 事件驱动 → revalidateTag + CMS Webhook
              │
              └── 实时变化 → 动态渲染
                    或 CSR / WebSocket / 轮询