001 Next.js教程—— 项目搭建

原创已于 2025-06-28 15:20:46 修改 · 559 阅读

22 ·

CC 4.0 BY-SA版权

文章标签：

#javascript #react.js #typescript

于 2025-06-28 15:18:06 首次发布

next 专栏收录该内容

2 篇文章

订阅专栏

项目安装

npx create-next-app@latest
#@后跟版本号 @latest是最新版的意思 @14.0.0就是搭建14.0.0版本的next脚手架

初始化方式：

创建一个NextJs项目
项目名叫nextjs-demo
使用 TypeScript
开启 ESLint 代码检测
使用 Css原子类（Tailwindcss）
不使用 src 作为根目录
使用 appRouter 的方式构建应用
使用 alias 别名来优化 import 文件引入
根目录 alias 默认匹配 @ 和 * 符号（可自定义输入）

next项目创建时的初始化选项

Next.js v14 核心目录结构

（默认使用 App Router，支持 React Server Components）

my-app/
├── app/                  # 核心路由目录 (App Router)
│   ├── (auth)/           # 路由组 (不改变URL结构)
│   ├── dashboard/        # 普通路由 (/dashboard)
│   │   ├── analytics/    # 嵌套路由 (/dashboard/analytics)
│   │   │   └── page.tsx  # 嵌套页面组件
│   │   ├── layout.tsx    # 仪表盘专属布局
│   │   └── page.tsx      # 仪表盘主页面
│   ├── blog/
│   │   ├── [slug]/       # 动态路由 (e.g. /blog/post-1)
│   │   │   └── page.tsx  
│   │   └── page.tsx      
│   ├── api/              # API 路由 (可选)
│   │   └── route.ts      
│   ├── favicon.ico       # 网站图标
│   ├── globals.css       # 全局CSS
│   ├── layout.tsx        # 根布局 (必须)
│   ├── page.tsx          # 首页 (/) 
│   ├── template.tsx      # 可复用的模板组件
│   ├── error.tsx         # 错误边界 (替代 _error.js)
│   ├── loading.tsx       # 加载状态 (Suspense)
│   └── not-found.tsx     # 404 页面
│
├── public/               # 静态资源
│   ├── images/           # 图片资源
│   └── robots.txt        # SEO配置
│
├── src/                  # 可选源码目录 (推荐)
│   ├── components/       # 通用组件
│   ├── lib/              # 工具函数
│   └── styles/           # 样式文件
│
├── .env                  # 环境变量
├── .eslintrc.json        # ESLint 配置
├── .gitignore            
├── next.config.js        # Next.js 配置
├── package.json          
├── middleware.ts         # 中间件 (路由守卫/重定向)
└── tsconfig.json         # TypeScript 配置

关键文件详解

1. `app/` 目录 (App Router)

layout.tsx
根布局文件，必须包含 <html> 和 <body> 标签：

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body className={inter.className}>{children}</body>
        </html>
      );
    }

Metadata API
替代 next/head，在 layout.tsx 中配置：

import type { Metadata } from "next";
export const metadata: Metadata = {
  title: "这是一个页面标题",
  description: "这是页面描述",
};

page.tsx
页面组件，默认导出的 React 组件：

  export default function Home() {
      return <h1>Hello, Next.js 14!</h1>;
    }

动态路由
使用 [folderName] 格式定义：

    app/
      └── blog/
          └── [slug]/
              └── page.tsx  # 通过 `params.slug` 获取参数

特殊文件
- loading.tsx：基于 Suspense 的加载状态
- error.tsx：局部错误处理
- not-found.tsx：自定义 404

2. 路由组 (Route Groups)

用 (folderName) 组织路由但不影响 URL 路径：

app/
  ├── (auth)/
  │   ├── login/
  │   │   └── page.tsx    # 路径仍为 /login
  │   └── register/
  │       └── page.tsx
  └── (marketing)/
      ├── about/
      └── contact/

3. 数据获取 (v14 优化)

在 Server Components 中直接使用 async/await：

// app/dashboard/page.tsx
export default async function Dashboard() {
  const data = await fetch("https://api.example.com/data");
  return <div>{data}</div>;
}

4. Server Actions

在组件内直接定义服务端操作（无需 API 路由）：

// app/actions.ts
"use server";
export async function createPost(formData: FormData) {
  // 服务端操作（数据库写入等）
}

5. 中间件 (`middleware.ts`)

全局请求拦截：

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith("/dashboard")) {
    // 验证用户权限
  }
}

Next.js的数据获取与渲染

1. 服务器组件（Server Components）

直接使用 async/await：在组件内发起请求，替代 getServerSideProps

// app/dashboard/page.tsx
export default async function Dashboard() {
  const data = await fetch('https://api.example.com/data');
  return <div>{data}</div>;
}

禁止使用 Hooks：服务器组件中不可用 useState、useEffect 等客户端 API

2. 渲染模式配置

通过 fetch 参数控制缓存策略：

模式	配置方式	适用场景
SSR	`{ cache: 'no-store' }`	实时数据（如用户仪表盘）2
SSG	`{ cache: 'force-cache' }`	静态内容（如博客）
ISR	`{ next: { revalidate: 60 } }`	增量更新（如商品列表）27

Next.js 的路由系统进阶

1. 并行路由（Parallel Routes）

用途：同一布局内同时渲染多个独立路由（如仪表盘多视图）。
约定：使用 @ 前缀定义插槽（Slots）。

app/
  └── dashboard/
      ├── @analytics/   # 插槽：@analytics
      │   └── page.tsx
      ├── @team/        # 插槽：@team
      │   └── page.tsx
      └── layout.tsx    # 通过 props 接收插槽

// layout.tsx
export default function Layout({ children, analytics, team }) {
  return (
    <>
      {children}
      <div>{analytics}</div> 
      <div>{team}</div>
    </>
  );
}

2. 拦截路由（Intercepting Routes）

用途：动态拦截路由跳转（如点击链接时弹出模态框而非跳页）。
约定：使用 (..) 语法匹配上级路由：

app/
  ├── @modal/          # 拦截层
  │   └── (..)photo/    # 匹配 photo/[id]
  │       └── [id].tsx
  └── photo/
      └── [id].tsx     # 原始路由

3. 路由组（Route Groups）

用途：组织路由文件（如按功能分类），不影响 URL 结构。
约定：(folderName) 格式1：

app/
  ├── (auth)/
  │   ├── login/page.tsx   # URL: /login
  │   └── register/page.tsx
  └── (marketing)/
      ├── about/page.tsx
      └── contact/page.tsx

Server Actions（稳定版）

用途：在组件内直接定义服务端逻辑（无需单独 API 路由）。
优势：减少网络请求、简化数据变更流程

// app/actions.ts
"use server";
export async function createPost(data: FormData) {
  await db.post.create({ data });
  revalidatePath('/posts'); // 刷新缓存
}

// 客户端调用
import { createPost } from '@/app/actions';
export default function Form() {
  return (
    <form action={createPost}>
      <input name="title" />
      <button>Submit</button>
    </form>
  );
}

开发体验优化

1. Turbopack 构建引擎（Beta）

性能提升：本地启动速度 ↑53%，热更新 ↑94%。
启用命令：next dev --turbo

2. 部分预渲染（Partial Prerendering - 预览）

原理：静态骨架 + 动态内容流式注入。
优势：兼顾静态页面速度与动态数据灵活性。

3. 元数据（Metadata API）

替代 next/head，在布局中配置 SEO:

// app/layout.tsx
export const metadata: Metadata = {
  title: 'My App',
  description: 'Built with Next.js 14',
};