linrunxinnn

一个意外来到地球的伪人正在学习前端开发

Announcement

Welcome to my blog! This is a sample announcement.

Learn More

1310 字

7 分钟

Nextjs入门

2025-10-14

前端

“前端”，“Next.js”

Next.js 入门#

本文总结了常见的 Next.js 概念与实践，包括项目创建、路由、layout、服务端/客户端组件、数据获取、错误/加载处理、元数据、Server Action 与中间件等。

创建项目#

使用官方脚手架创建一个 Next.js 项目：

1
npx create-next-app@latest

注意：Node 环境要求 v18.18 及以上。

路由（基于文件系统）#

Next.js 的路由基于文件系统，一个文件夹代表一个路由，因此通常不需要使用 react-router。

创建页面#

在 app 目录下创建对应的文件夹，然后在该文件夹中创建 page.tsx（或 page.jsx），并导出一个 React 组件。该页面组件会被插入到对应层级的 layout 组件中。

动态路由#

通过在文件夹名中使用中括号创建动态路由，例如：

1
-[id]
2
  |_ work
3
      |_ page.js

将会对应路由 /:id/work。

路由跳转#

Link 组件：用于声明式导航。
useRouter：用于编程式导航，提供 push、replace、back、refresh 等方法。

useRouter 示例#

1
'use client'
2
import { useRouter } from 'next/navigation';
3

4
export default function MyComponent() {
5
  const router = useRouter();
6
  return (
7
    <button onClick={() => router.push('/about')}>Go to About</button>
8
  );
9
}

路由组#

使用小括号包裹文件夹名，创建一个路由组用于分组但不作为路由层级，例如：

1
app/
2
  dashboard/
3
    (layout)/
4
      personal/
5
        page.jsx
6
      analyse/
7
        page.jsx

路由组用于模块划分和共享布局。

layout（布局）#

在任意 app 目录下定义 layout.tsx，导出一个组件作为该层级及以下共享的框架。layout 组件需要接收 children 参数，默认为服务端组件：

1
import SideNav from './nav-link'
2

3
export default function Layout({ children }: { children: React.ReactNode }) {
4
  return (
5
    <div className="flex h-screen">
6
      <div className="w-64">
7
        <SideNav />
8
      </div>
9
      <div className="flex-1">{children}</div>
10
    </div>
11
  )
12
}

切换页面时，layout 不会重新加载（保留状态）。

服务端组件与客户端组件#

Next.js 将默认组件视为服务端组件。若要将组件设为客户端组件，需要在文件顶部添加 "use client"。

服务端组件（Server Components）#

在服务器上渲染（返回 HTML）。
不能使用浏览器 API 或 React client hooks。
可以直接访问数据库或其他服务器资源。

客户端组件（Client Components）#

在浏览器端运行。
支持交互与状态（可以使用 React hooks）。
不能直接访问服务器资源（需通过 fetch/API 获取）。

推荐：服务端负责数据，客户端负责交互#

父组件可以是服务端组件，内部嵌套客户端组件进行交互。

数据获取方式#

建议在服务端组件中进行数据请求，这样对 SEO 更友好，并能使用 Next.js 的缓存与 revalidate。常见方式：

1) 在服务端组件中直接使用 await + fetch#

1
export default async function Page() {
2
  const res = await fetch('https://api.example.com/users')
3
  const users = await res.json()
4

5
  return (
6
    <ul>
7
      {users.map((u: any) => (
8
        <li key={u.id}>{u.name}</li>
9
      ))}
10
    </ul>
11
  )
12
}

2) 直接使用服务器资源#

服务端组件可直接与数据库或本地服务代码交互（在安全的环境下）。

3) Next.js 缓存机制与 revalidate#

（此处可补充：fetch 的 cache、next revalidate 选项，以及 ISR 的使用示例）

4) generateStaticParams / generateMetadata#

用于静态生成时提供参数或动态构造页面元数据（后面示例中会展示）。

客户端组件的数据获取#

使用 useEffect + fetch
使用 SWR 等客户端数据库

流式渲染与 loading#

loading.tsx 是约定文件，用于在路由数据尚未准备好时显示占位 UI。Next.js 会在异步组件外层自动使用 Suspense。

1
<Suspense fallback={<Loading />}>
2
  <Page />
3
</Suspense>

错误处理#

error.tsx 用于捕获渲染错误并显示回退 UI（此文件通常为客户端组件）：

1
'use client'
2

3
export default function Error({ error, reset }: { error: Error; reset: () => void }) {
4
  return (
5
    <div className="flex flex-col items-center justify-center h-screen">
6
      <h2 className="text-red-600 text-2xl font-bold">出错了 😢</h2>
7
      <p className="mt-2 text-gray-600">{error.message}</p>
8
      <button onClick={() => reset()} className="mt-4 px-4 py-2 bg-blue-600 text-white rounded">重试</button>
9
    </div>
10
  )
11
}

404 页面处理（not-found.tsx）#

not-found.tsx 用于处理 404 状态。示例：

1
export default function NotFound() {
2
  return (
3
    <div className="flex flex-col items-center justify-center h-screen">
4
      <h2 className="text-3xl font-bold text-red-600">404 - 页面未找到 😢</h2>
5
      <p className="mt-2 text-gray-600">请检查您访问的地址是否正确。</p>
6
    </div>
7
  )
8
}

服务端手动触发 404：

1
import { notFound } from 'next/navigation'
2

3
export default async function Page() {
4
  const res = await fetch('https://api.example.com/user/123')
5

6
  if (!res.ok) {
7
    notFound() // 手动触发 404 页面
8
  }
9

10
  const data = await res.json()
11
  return <div>{data.name}</div>
12
}

元数据（Metadata）#

通过在 layout.tsx 或 page.tsx 导出元数据对象或 generateMetadata 函数来设置页面的元信息，利于 SEO。

静态元数据#

1
export const metadata = {
2
  title: "",
3
  description: "",
4
  keywords: [""],
5
}

动态 generateMetadata#

1
import { Metadata } from 'next'
2

3
export async function generateMetadata({ params }: { params: { id: string } }): Promise<Metadata> {
4
  const post = await fetch(`https://api.example.com/posts/${params.id}`).then(res => res.json())
5

6
  return {
7
    title: post.title,
8
    description: post.summary,
9
    openGraph: {
10
      title: post.title,
11
      description: post.summary,
12
      images: [post.coverImage],
13
    },
14
  }
15
}

服务端行为（Server Actions）#

Server Action 允许在服务器上运行函数并由客户端直接调用（不经过 HTTP API）。

1
'use server'
2

3
import { db } from '@/lib/db'
4

5
export async function createUser(data: { name: string; email: string }) {
6
  const user = await db.user.create({ data })
7
  return user
8
}

Server Action 可直接绑定表单并传递复杂数据结构，Next.js 会自动序列化。

中间件（middleware）#

中间件在请求到达页面或 API 之前执行，可用于重定向、认证、日志等。

1
import { NextResponse } from 'next/server'
2
import type { NextRequest } from 'next/server'
3

4
export function middleware(request: NextRequest) {
5
  const { pathname } = request.nextUrl
6
  const isLoggedIn = request.cookies.get('token')?.value
7

8
  if (pathname.startsWith('/dashboard') && !isLoggedIn) {
9
    return NextResponse.redirect(new URL('/login', request.url))
10
  }
11

12
  return NextResponse.next()
13
}
14

15
export const config = {
16
  matcher: ['/dashboard/:path*', '/profile/:path*']
17
}