Next.js — React 全栈框架完全指南

// 错误做法
function Component() {
  return <p>{typeof window !== 'undefined' ? 'client' : 'server'}</p>
}

// 正确做法
'use client'
function Component() {
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])
  return <p>{mounted ? 'client' : 'server'}</p>
}

'use client' // 必须是文件的第一行（注释除外）

import { useState } from 'react'

export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

<time suppressHydrationWarning>
  {new Date().toLocaleDateString()}
</time>

npm install @types/react@latest @types/react-dom@latest typescript@latest

import { Suspense } from 'react'

function SearchBar() {
  return (
    <Suspense fallback={<div>加载中...</div>}>
      <SearchBarContent />
    </Suspense>
  )
}

// lib/db.ts
import 'server-only'
import { prisma } from './prisma'
export async function getUser(id: string) {
  return prisma.user.findUnique({ where: { id } })
}

import dynamic from 'next/dynamic'

const MapComponent = dynamic(() => import('./Map'), {
  ssr: false,
  loading: () => <p>地图加载中...</p>
})

'use client'
export { Button } from 'antd' // 重新导出为客户端组件

// 错误：Server Component 中 fetch 自己的 API
const res = await fetch('http://localhost:3000/api/posts')

// 正确：直接调用业务函数
import { getPosts } from '@/lib/posts'
const posts = await getPosts()

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

npm install @next/bundle-analyzer
# 在 next.config.js 中配置后运行：
ANALYZE=true npm run build

// next.config.js（Next.js 15 常用配置）
/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: '**.example.com' },
    ],
  },
}
module.exports = nextConfig

// next.config.js
module.exports = {
  transpilePackages: ['some-package'],
}

# 确保 React 版本匹配
npm ls react react-dom

# 清理重装
rm -rf node_modules .next package-lock.json
npm install

# Next.js 15 需要 React 19
npm install react@latest react-dom@latest next@latest

// App Router — 使用 next/navigation
import { useRouter } from 'next/navigation'

// Pages Router（旧版）— 使用 next/router
import { useRouter } from 'next/router'

// Next.js 15 正确写法
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  // ...
}

// Next.js 14 旧写法（不再适用于 15）
export default function Page({ params }: { params: { slug: string } }) {
  const { slug } = params
}

my-app/
├── middleware.ts    ✅ 正确位置
├── app/
│   ├── middleware.ts  ❌ 不会生效
│   └── page.tsx

// app/layout.tsx
export default function Layout({
  children,
  modal, // 对应 app/@modal/page.tsx
}: {
  children: React.ReactNode
  modal: React.ReactNode
}) {
  return (
    <>
      {children}
      {modal}
    </>
  )
}

// 正确 — 客户端导航
import Link from 'next/link'
<Link href="/about">关于我们</Link>

// 错误 — 完整页面刷新
<a href="/about">关于我们</a>

// middleware.ts — 正确的 matcher
export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|login).*)',
  ],
}

// 确保返回正确的参数格式
export async function generateStaticParams() {
  const posts = await db.post.findMany()
  return posts.map((post) => ({
    slug: post.slug, // 键名必须与文件夹名 [slug] 匹配
  }))
}

// 允许按需生成未预渲染的页面
export const dynamicParams = true

// 禁用缓存（每次获取最新数据）
const res = await fetch(url, { cache: 'no-store' })

// 定时重新验证
const res = await fetch(url, { next: { revalidate: 60 } })

// 使用标签按需重新验证
const res = await fetch(url, { next: { tags: ['posts'] } })
// 在 Server Action 中：revalidateTag('posts')

'use server'
export async function getUser(id: string) {
  const user = await db.user.findUnique({ where: { id } })
  return {
    ...user,
    createdAt: user.createdAt.toISOString(), // Date → string
  }
}

// lib/prisma.ts
import { PrismaClient } from '@prisma/client'

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined
}

export const prisma = globalForPrisma.prisma ?? new PrismaClient()

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma

// app/api/data/route.ts
export const dynamic = 'force-dynamic'

export async function GET() {
  const data = await getData()
  return Response.json(data)
}

// 错误：串行（慢）
const user = await getUser(id)
const posts = await getPosts(id)
const comments = await getComments(id)

// 正确：并行（快）
const [user, posts, comments] = await Promise.all([
  getUser(id),
  getPosts(id),
  getComments(id),
])

import { unstable_cache } from 'next/cache'

const getCachedPosts = unstable_cache(
  async () => {
    return db.post.findMany()
  },
  ['posts'],           // 缓存键
  { revalidate: 3600, tags: ['posts'] } // 选项
)

const posts = await getCachedPosts()

# .env.local
DATABASE_URL=xxx           # 仅服务端可用
NEXT_PUBLIC_API_URL=xxx    # 客户端和服务端都可用

npm install sharp

# Docker Alpine 镜像中可能需要额外依赖
RUN apk add --no-cache libc6-compat

module.exports = {
  images: { unoptimized: true }
}

# Dockerfile 中
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/static ./.next/static

// next.config.js
module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0, // 禁用内存缓存
}

// app/api/data/route.ts
export async function GET() {
  const data = await getData()
  return new Response(JSON.stringify(data), {
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type',
    },
  })
}

export async function OPTIONS() {
  return new Response(null, {
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type',
    },
  })
}

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'cdn.example.com',
        pathname: '/images/**',
      },
      {
        protocol: 'https',
        hostname: '**.amazonaws.com',
      },
    ],
  },
}

// middleware.ts
import createMiddleware from 'next-intl/middleware'

export default createMiddleware({
  locales: ['zh', 'en', 'ja'],
  defaultLocale: 'zh',
})

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