跳到主要内容

Next.js 完整教程（新手向）

阅读需 3 分钟

本教程面向零基础或刚接触 Next.js 的开发者，按由浅入深的顺序讲解所有主要知识点。建议按章节顺序阅读。

一、Next.js 简介​

什么是 Next.js？​

Next.js 是一个基于 React 的 Web 框架，提供了路由、渲染与构建能力，让你更容易构建：

  • SSR / SSG / 混合渲染应用
  • 全栈 Web（配合 API / Route Handler）
  • 类型友好的工程化开发体验

适合做什么？​

  • 个人博客 / 技术文章站
  • 产品官网与落地页
  • 带用户登录、后台管理的 Web 应用（配合你选择的认证方案）
  • API 与前后端一体化项目

二、环境准备与创建项目​

环境要求​

  • Node.js：建议使用 18.x 及以上（推荐 20 LTS）
  • 了解基础的 npm/pnpm/yarn 使用

创建项目​

使用官方推荐的脚手架 create-next-app：

npx create-next-app@latest my-next-app

初始化安装完成后进入目录并启动：

cd my-next-app
npm run dev

浏览器打开 http://localhost:3000 即可。

新手提示

如果你在 WSL / 远程环境访问开发服务器，可能需要让 Next.js 监听所有网卡（或通过端口转发访问）。

三、App Router（推荐）与基础目录结构​

Next.js（新版本）通常使用 App Router。常见目录结构如下：

my-next-app/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── api/
│       └── health/route.ts
├── public/
├── src/ (可选：把组件/业务逻辑放这里)
├── package.json
└── next.config.js

关键约定：

  • app/layout.tsx：全站的根布局（所有页面都会套在里面）
  • app/page.tsx：/ 路由对应的页面
  • app/**/page.tsx：app 下的每个文件夹可对应一个路由

四、路由与页面（Page / Layout）​

页面：page.tsx​

创建一个路由 app/about/page.tsx：

// app/about/page.tsx
export default function AboutPage() {
  return (
    <main>
      <h1>About</h1>
      <p>这是一个 /about 页面。</p>
    </main>
  )
}

使用 Next.js 的 Link 进行跳转（推荐）：

import Link from 'next/link'

export default function Home() {
  return (
    <main>
      <h1>Home</h1>
      <Link href="/about">去 About</Link>
    </main>
  )
}

五、组件与样式（CSS Modules / 全局样式）​

CSS Modules​

假设你有 app/components/Hello.module.css：

.title {
  color: #2e8555;
}

然后在组件中使用：

import styles from './Hello.module.css'

export default function Hello() {
  return <h1 className={styles.title}>Hello Next.js</h1>
}

全局样式​

通常在 app/globals.css 引入全站样式，并在根布局 layout.tsx 中导入。

六、数据获取（Data Fetching）​

在 App Router 下，你常见会遇到几种数据获取方式：

  1. Server Components 里直接 fetch（最常见的新手路径）
  2. 使用 Route Handler 提供 API，再在客户端请求
  3. 需要更复杂缓存策略时，显式配置 Next.js 的缓存行为

服务端 fetch 示例​

app/posts/page.tsx：

export default async function PostsPage() {
  const res = await fetch('https://jsonplaceholder.typicode.com/posts', {
    // 新手先用默认策略即可；需要时再研究缓存/重验证
    cache: 'no-store',
  })
  const posts = await res.json()

  return (
    <main>
      <h1>Posts</h1>
      <ul>
        {posts.slice(0, 5).map((p: any) => (
          <li key={p.id}>{p.title}</li>
        ))}
      </ul>
    </main>
  )
}

七、Route Handler（类似 API 路由）​

在 App Router 中，你可以在 app/api/.../route.ts 里写接口。

例如 app/api/health/route.ts：

import { NextResponse } from 'next/server'

export async function GET() {
  return NextResponse.json({ ok: true })
}

访问：/api/health

你也可以扩展为 POST / PUT / DELETE 等方法。

八、构建与部署​

构建​

npm run build

本地预览​

npm run start

部署到 Vercel（新手最省事）​

Next.js 官方在 Vercel 上体验最佳。一般步骤：

  • 把项目推到 GitHub
  • 在 Vercel 创建新项目并导入仓库
  • 使用 Vercel 默认构建命令（通常就是 npm run build）

九、常见问题与小结​

常见问题​

  • 为什么我写的页面路由不生效？
    • 确认 app 目录下的 page.tsx 是否放对路径（例如 app/about/page.tsx 对应 /about）
  • 为什么数据没有更新？
    • App Router 下 fetch 的缓存策略可能不同；新手阶段可先用 cache: 'no-store'

小结​

  • 用 app/ 组织路由：layout.tsx + page.tsx
  • 用 Link 做跳转
  • 用 CSS Modules 管理样式
  • 在 Server Components 中 fetch 获取数据
  • 用 app/api/.../route.ts 提供接口
  • 用 npm run build / npm run start 完成构建与预览

十、学习路径小结​

  1. 新建 Next.js 项目并跑通 npm run dev
  2. 写 layout.tsx 和一个 about/page.tsx
  3. 用 Link 做页面跳转
  4. 写一个 fetch 示例页面并观察加载行为
  5. 写 app/api/health/route.ts 测试接口
  6. 完成 npm run build 与本地 npm run start 预览

遇到问题可查阅 Next.js 官方文档。

Loading Comments...