Next.js 全指南：从入门到精通.

// app/page.tsx → 对应路由 /
export default function HomePage() {
  return <h1>这是首页</h1>;
}
 
// app/about/page.tsx → 对应路由 /about
export default function AboutPage() {
  return <h1>关于我们</h1>;
}
 
// app/blog/[id]/page.tsx → 对应路由 /blog/123（动态路由）
export default async function BlogPost({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  return <h1>文章 {id}</h1>;
}

// app/layout.tsx → 根布局（必须有 html 和 body 标签）
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh">
      <body>
        <nav>导航栏（导航时不重新渲染）</nav>
        <main>{children}</main>
      </body>
    </html>
  );
}

// Server Component（默认）- 在服务端运行，发送 HTML 到客户端
// app/page.tsx
import { db } from "@/lib/db";
import LikeButton from "./like-button";
 
export default async function Page() {
  const posts = await db.query("SELECT * FROM posts"); // 直接访问数据库
  return (
    <div>
      {posts.map((post) => (
        <p key={post.id}>{post.title}</p>
      ))}
      <LikeButton /> {/* 交互部分交给 Client Component */}
    </div>
  );
}

// Client Component - 需要交互时添加 "use client"
// app/like-button.tsx
"use client";
 
import { useState } from "react";
 
export default function LikeButton() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>赞 {count}</button>;
}

// Server Component 中直接 fetch
export default async function BlogPage() {
  const res = await fetch("https://api.example.com/posts");
  const posts = await res.json();
 
  return (
    <ul>
      {posts.map((post: any) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

// next.config.ts 中启用
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
  cacheComponents: true,
};
export default nextConfig;

// 数据级缓存
import { cacheLife } from "next/cache";
 
export async function getUsers() {
  "use cache";
  cacheLife("hours"); // 缓存一小时
  return db.query("SELECT * FROM users");
}

// UI 级缓存
import { cacheLife } from "next/cache";
 
export default async function BlogPosts() {
  "use cache";
  cacheLife("hours");
  const posts = await fetch("https://api.example.com/posts");
  return <div>{/* 渲染文章列表 */}</div>;
}

// app/actions.ts
"use server";
 
import { revalidateTag } from "next/cache";
 
export async function createPost(formData: FormData) {
  await db.post.create({
    data: { title: formData.get("title") as string },
  });
  revalidateTag("posts"); // 刷新缓存
}

// 在表单中使用
import { createPost } from "./actions";
 
export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" placeholder="文章标题" />
      <button type="submit">发布</button>
    </form>
  );
}

npx create-next-app@latest

npm install next@latest react@latest react-dom@latest

// package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

// app/layout.tsx - 根布局（必需）
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh">
      <body>{children}</body>
    </html>
  );
}

// app/blog/layout.tsx - 嵌套布局
export default function BlogLayout({ children }: { children: React.ReactNode }) {
  return (
    <section>
      <h2>博客</h2>
      {children}
    </section>
  );
}

import Link from "next/link";
 
export default function NavBar() {
  return (
    <nav>
      <Link href="/">首页</Link>
      <Link href="/about">关于</Link>
      <Link href="/blog/123">文章</Link>
    </nav>
  );
}

// app/blog/[id]/page.tsx
export default async function BlogPost({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  return <h1>文章 ID: {id}</h1>;
}

// app/blog/loading.tsx - 自动 Suspense 边界
export default function Loading() {
  return <div>加载中...</div>;
}

// app/error.tsx - 必须是 Client Component
"use client";
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div>
      <h2>出错了！</h2>
      <button onClick={reset}>重试</button>
    </div>
  );
}

// app/api/posts/route.ts
import { NextResponse } from "next/server";
 
export async function GET() {
  const posts = await db.query("SELECT * FROM posts");
  return NextResponse.json(posts);
}
 
export async function POST(request: Request) {
  const body = await request.json();
  const post = await db.post.create({ data: body });
  return NextResponse.json(post, { status: 201 });
}

// app/page.tsx（Server Component）
import LikeButton from "./like-button";
import { getPost } from "@/lib/data";
 
export default async function Page() {
  const post = await getPost("1");
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
      <LikeButton likes={post.likes} />
    </article>
  );
}

// app/ui/modal.tsx（Client Component）
"use client";
 
export default function Modal({ children }: { children: React.ReactNode }) {
  return <div className="modal">{children}</div>;
}

// app/page.tsx（Server Component）
import Modal from "./ui/modal";
import Cart from "./ui/cart"; // Cart 是 Server Component
 
export default function Page() {
  return (
    <Modal>
      <Cart /> {/* Server Component 作为 children 传入 Client Component */}
    </Modal>
  );
}

// app/theme-provider.tsx
"use client";
 
import { createContext } from "react";
 
export const ThemeContext = createContext("light");
 
export default function ThemeProvider({ children }: { children: React.ReactNode }) {
  return <ThemeContext.Provider value="dark">{children}</ThemeContext.Provider>;
}

// app/layout.tsx
import ThemeProvider from "./theme-provider";
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

import { Suspense } from "react";
 
export default function Page() {
  return (
    <>
      <h1>我的博客</h1>
      {/* 这部分立即显示 */}
      <p>欢迎来到我的博客</p>
      {/* 这部分在数据加载完成后流式显示 */}
      <Suspense fallback={<div>加载文章中...</div>}>
        <BlogPosts />
      </Suspense>
      <Suspense fallback={<div>加载评论中...</div>}>
        <Comments />
      </Suspense>
    </>
  );
}

// 多个请求同时发起
export default async function Page() {
  const artistPromise = getArtist();
  const albumsPromise = getAlbums();
 
  const [artist, albums] = await Promise.all([artistPromise, albumsPromise]);
 
  return (
    <div>
      <h1>{artist.name}</h1>
      <AlbumList albums={albums} />
    </div>
  );
}

export default async function Page() {
  const artist = await getArtist(); // 先获取 artist
  const playlists = await getPlaylists(artist.id); // 再用 artist.id 获取
  return <div>{/* ... */}</div>;
}

import { cacheLife, cacheTag } from "next/cache";
 
// 数据级缓存 + 标签
export async function getProducts() {
  "use cache";
  cacheLife("hours"); // 缓存存活时间
  cacheTag("products"); // 缓存标签，用于按需刷新
  return db.query("SELECT * FROM products");
}

"use cache";
cacheLife("seconds"); // 每秒刷新
cacheLife("minutes"); // 每分钟刷新
cacheLife("hours"); // 每小时刷新
cacheLife("days"); // 每天刷新
cacheLife("weeks"); // 每周刷新
cacheLife("max"); // 最大缓存

// app/actions.ts
"use server";
import { revalidateTag, revalidatePath, updateTag } from "next/cache";
 
export async function refreshProducts() {
  revalidateTag("products"); // 刷新带 'products' 标签的所有缓存
}
 
export async function refreshPage() {
  revalidatePath("/products"); // 刷新 /products 路径的所有缓存
}
 
export async function updateProducts() {
  updateTag("products"); // 立即过期并重新生成
}

import { cookies } from "next/headers";
import { Suspense } from "react";
 
async function UserGreeting() {
  const cookieStore = await cookies();
  const theme = cookieStore.get("theme")?.value || "light";
  return <p>你的主题: {theme}</p>;
}
 
export default function Page() {
  return (
    <>
      <h1>仪表盘</h1>
      <Suspense fallback={<p>加载中...</p>}>
        <UserGreeting />
      </Suspense>
    </>
  );
}

// app/layout.tsx - 静态 metadata
export const metadata = {
  title: "我的网站",
  description: "这是我的网站描述",
};
 
// app/blog/[id]/page.tsx - 动态 metadata
export async function generateMetadata({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const post = await getPost(id);
  return {
    title: post.title,
    description: post.excerpt,
  };
}

import "server-only"; // 阻止客户端导入
 
export async function getData() {
  const res = await fetch("https://api.example.com/data", {
    headers: { authorization: process.env.API_KEY },
  });
  return res.json();
}

// 正确做法：只在需要交互的组件上加 "use client"
// app/layout.tsx - 这是 Server Component
import Search from "./search"; // Client Component
import Logo from "./logo"; // Server Component
 
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <nav>
        <Logo />
        <Search /> {/* 只有搜索栏是 Client Component */}
      </nav>
      <main>{children}</main>
    </>
  );
}

import { cache, createContext } from "react";
 
// 创建缓存函数，同一请求内多次调用只执行一次
const getUser = cache(async (id: string) => {
  return db.user.findUnique({ where: { id } });
});

// app/carousel.tsx
"use client";
import { Carousel } from "acme-carousel";
export default Carousel;

// app/api/route.ts
export const dynamic = "force-dynamic"; // 强制动态渲染
export const revalidate = 0; // 禁用缓存
export const runtime = "edge"; // 使用 Edge Runtime
export const maxDuration = 60; // 最大执行时间（秒）