Next.js 速查表（2025 App Router）：API、配置与决策矩阵

// 默认行为（Next.js 15）：请求记忆 + 数据缓存
fetch('https://api.example.com/data');

// 完全禁用缓存（类似 SSR）
fetch('https://api.example.com/data', { cache: 'no-store' });

// ISR：缓存 1 小时后后台刷新
fetch('https://api.example.com/data', { next: { revalidate: 3600 } });

// 带标签缓存（支持按需失效）
fetch('https://api.example.com/posts', { next: { tags: ['posts'] } });

// 永久缓存（类似 SSG）
fetch('https://api.example.com/static', { cache: 'force-cache' });

// 页面级别缓存控制
export const revalidate = 60;           // ISR 60 秒
export const dynamic = 'force-dynamic';  // SSR（无缓存）
export const dynamicParams = false;      // 只预生成已知路径

// 定义 Server Action（可直接绑定到 <form>）
async function createPost(formData: FormData) {
  'use server';
  const title = formData.get('title') as string;
  await prisma.post.create({ data: { title } });
  revalidatePath('/posts');
}

// 带错误处理和返回值的 Server Action
async function submitContact(formData: FormData) {
  'use server';
  const email = formData.get('email') as string;

  if (!email.includes('@')) {
    return { error: 'Invalid email' };
  }

  try {
    await sendEmail(email);
    return { success: true };
  } catch {
    return { error: 'Failed to send' };
  }
}

// 前端：用 useFormState 处理返回
'use client';
import { useFormState } from 'react-dom';

export default function ContactForm() {
  const [state, formAction] = useFormState(submitContact, { error: null });

  return (
    <form action={formAction}>
      <input name="email" type="email" required />
      <button type="submit">Send</button>
      {state?.error && <p>{state.error}</p>}
      {state?.success && <p>Sent!</p>}
    </form>
  );
}

// useOptimistic：乐观更新
const [optimisticState, addOptimistic] = useOptimistic(
  initialState,
  (current, newItem) => [...current, newItem]
);

async function handleSubmit(formData: FormData) {
  addOptimistic({ id: 'temp', title: formData.get('title') });
  await serverAction(formData);
}

// page.tsx / layout.tsx
import { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'My Page',
  description: 'Page description for SEO',

  openGraph: {
    title: 'My Page',
    description: 'OG description',
    images: ['/og-image.jpg'],
  },

  twitter: {
    card: 'summary_large_image',
    title: 'My Page',
    images: ['/twitter-image.jpg'],
  },

  robots: {
    index: true,
    follow: true,
  },

  alternates: {
    canonical: 'https://example.com/page',
    languages: {
      'en-US': '/en/page',
      'zh-CN': '/zh/page',
    },
  },
};

// 动态 Metadata（基于路由参数）
export async function generateMetadata({ params }): Promise<Metadata> {
  const post = await getPost(params.slug);
  return {
    title: post.title,
    description: post.excerpt,
  };
}

// app/error.tsx（局部错误边界）
'use client';

export default function Error({ error, reset }: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong</h2>
      <p>{error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

// app/global-error.tsx（全局错误）
'use client';

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <h2>Global Error</h2>
        <button onClick={reset}>Reload</button>
      </body>
    </html>
  );
}

// 主动抛出 404
import { notFound } from 'next/navigation';

export default async function Page({ params }) {
  const post = await getPost(params.slug);
  if (!post) notFound(); // 渲染 not-found.tsx
  return <Post post={post} />;
}

// middleware.ts（项目根目录）
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // 认证检查
  const token = request.cookies.get('token')?.value;
  if (!token && pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  // i18n 重定向
  if (!pathname.startsWith('/en') && !pathname.startsWith('/zh')) {
    return NextResponse.redirect(new URL('/en' + pathname, request.url));
  }

  // URL 重写（URL 不变，内部路由改变）
  if (pathname === '/docs') {
    return NextResponse.rewrite(new URL('/documentation', request.url));
  }

  // 注入请求头
  const headers = new Headers(request.headers);
  headers.set('x-user-country', request.geo?.country || 'US');
  return NextResponse.next({ request: { headers } });
}

// 匹配规则
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // 独立运行模式（Docker 必需）
  output: 'standalone',

  // 图片配置
  images: {
    domains: ['cdn.example.com'],
    remotePatterns: [
      { protocol: 'https', hostname: '**.example.com' },
    ],
    formats: ['image/avif', 'image/webp'],
  },

  // 重写规则
  async rewrites() {
    return [
      { source: '/old-path', destination: '/new-path' },
      { source: '/api/:path*', destination: 'https://api.example.com/:path*' },
    ];
  },

  // 重定向
  async redirects() {
    return [
      { source: '/about-us', destination: '/about', permanent: true },
    ];
  },

  // 请求头
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          { key: 'X-Frame-Options', value: 'DENY' },
        ],
      },
    ];
  },

  // TypeScript/ESLint 构建时检查（临时禁用）
  typescript: { ignoreBuildErrors: false },
  eslint: { ignoreDuringBuilds: false },

  // 实验性功能
  experimental: {
    ppr: true,              // 部分预渲染
    dynamicIO: true,        // 动态 IO（Next.js 15+）
    after: true,            // after() API
  },
};

export default nextConfig;

# 创建项目
npx create-next-app@latest my-app --typescript --tailwind --app

# 开发
npm run dev          # 启动开发服务器（默认 Turbopack）
npm run dev --turbo  # 显式启用 Turbopack

# 构建
npm run build        # 生产构建
npm start            # 启动生产服务器（需先 build）

# 分析 Bundle
npm install @next/bundle-analyzer
# next.config.js: ANALYZE=true npm run build

# 类型检查
npx tsc --noEmit

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
  analytics,
  revenue,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  revenue: React.ReactNode;
}) {
  return (
    <div className="grid grid-cols-2 gap-4">
      <div>{analytics}</div>
      <div>{revenue}</div>
      <div className="col-span-2">{children}</div>
    </div>
  );
}

// app/api/stream/route.ts
export async function GET() {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    start(controller) {
      let count = 0;
      const interval = setInterval(() => {
        controller.enqueue(encoder.encode(`data: ${++count}\n\n`));
        if (count >= 5) {
          clearInterval(interval);
          controller.close();
        }
      }, 1000);
    },
  });

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      Connection: 'keep-alive',
    },
  });
}

// 支持多种 HTTP 方法的统一文件
export async function POST(request: Request) {
  const body = await request.json();
  // ...处理逻辑
  return Response.json({ id: 1, ...body }, { status: 201 });
}

export async function PUT(request: Request) { /* ... */ }
export async function DELETE(request: Request) { /* ... */ }

// app/api/revalidate/route.ts
import { revalidateTag, revalidatePath } from 'next/cache';

export async function POST(request: Request) {
  const { slug } = await request.json();

  // 方式 1：按标签失效（fine-grained）
  revalidateTag(`post-${slug}`);

  // 方式 2：按路径失效（coarse-grained）
  revalidatePath(`/blog/${slug}`);

  return Response.json({ revalidated: true, now: Date.now() });
}

import Image from 'next/image';

// 使用外部图片需先在 next.config.js 中配置 domains/remotePatterns
<Image
  src="https://cdn.example.com/hero.jpg"
  alt="Hero"
  width={1200}
  height={630}
  priority        // 首屏图片：preload，跳过懒加载
  quality={85}    // 默认 75，可调整
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
  sizes="(max-width: 768px) 100vw, 50vw"
/>

// middleware.ts —— 语言路由 + 内容协商
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const locales = ['en', 'zh', 'ja'];
const defaultLocale = 'en';

export function middleware(request: NextRequest) {
  const pathname = request.nextUrl.pathname;
  const pathnameLocale = locales.find((l) => pathname.startsWith(`/${l}`));

  if (!pathnameLocale) {
    // 根据 Accept-Language 或 Cookie 推断语言
    const acceptLang = request.headers.get('accept-language')?.split(',')[0]?.split('-')[0];
    const locale = locales.includes(acceptLang) ? acceptLang : defaultLocale;
    return NextResponse.redirect(new URL(`/${locale}${pathname}`, request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/((?!api|_next|\\..*).*)'],
};

// 在 Route Handler 中指定运行时
export const runtime = 'edge';  // 'nodejs' | 'edge'
export const preferredRegion = 'iad1';  // 强制部署到华盛顿地区

import NextAuth from 'next-auth';
import { authConfig } from './auth.config'; // 不含 Prisma 等 Node-only 依赖

export const { auth, signIn, signOut, handlers } = NextAuth(authConfig);