Next.js 是基于 React 的全栈 Web 开发框架，由 Vercel 维护。它把路由、数据获取、渲染策略和性能调整都封装成一套约定。让你专注于编写页面和组件，而不是花时间在配置和工具链上。

主要特点一句话概括

• 文件即路由app 目录下的文件夹结构自动生成路由，不需要手写路由配置。不过，
• 渲染灵活同一项目内可以混合使用静态生成、服务端渲染和增量静态再生成。页面粒度控制，
• 服务端优先默认组件在服务端运行。直接异步获取数据，不用 useEffect；需要交互时才用 'use client' 标记客户端组件。
• 零配置调整内置图片、字体、脚本调整。自动代码分割，按需加载，建立即产出高性能应用。
• 全栈能力提供 API 路由、中间件、Server Actions，前后端代码写在一个项目里无需额外搭建后端服务。

一句话记忆 Next.js 就是一套让 React 开发更快、更规范、上线更轻松的全栈框架。

必会基础

页面与路由

一句话定义：Next.js 根据 app 目录下的文件夹和特殊文件自动生成路由，page.js 产生可访问的页面layout.js 提供可复用的外壳。

// app/posts//page.tsx
// 访问 /posts/hello-world 即会渲染此组件，params 由框架传入
export default async function PostPage {
const { slug } = await params;return，其实，}
// app/posts/layout.tsx
// 所有 /posts/* 页面都会包裹在此布局内。导航时布局不卸载
export default function PostsLayout {
return (


{children}

);}

典型场景

• 创建新页面 — 新建文件夹，放 page.tsx 即可。
• 同一模块共享导航栏、侧边栏 — 为该文件夹添加 layout.tsx.
• 需要 SEO 友好的动态路由 — 用 .

常见痛点 & 对策

• P1：layout.tsx 中误用了路由参数导致数据不刷新。说到⚡️方法，把依赖参数的数据逻辑搬到对应的 a page.tsx.
• P2：# 页面默认是服务端组件。却尝试使用客户端 Hook 报错。⚡️方法的观点是，在需要交互的地方新建一个带 “'use client'` 的子组件。

原理/细节：A​pp Router 基于文件程序约定映射 URL：文件夹 → 方法片段。*page*.js 为叶子节点，*layout*.js 为包裹器，实现“看目录就懂路由”。

服务端数据获取

一句话定义：服务端组件可以直接是一个 async) 函数。在函数体内用 alert fetch ) 请求数据，Next.js 会自动缓存、去重，并让数据在服务端注入 HTML。

// app/posts/page.tsx
async function getPosts {
// 默认 force‑cache，相当于 SSG 行为
const res = await fetch;怎么说呢，return res.json;}
export default async function PostsPage {
const posts = await getPosts;return (

{posts.map => (

{p.title}
))}

);}

Pain Point – 数据未更新或空白：

• 至于P1，忘记为动态需求关闭缓存导致页面一直显示旧数据。⚡️对策这方面，在 fetch 中加入 { next: { revalidate: X } }{ cache: 'no-store' }.
• P2的观点是。仅依赖 async 获取，却没有配套的 loading / error 界面。⚡️对策的观点是，创建同层级的 /loading.tsx /error.tsx .

SIDE NOTE：This code只能在服务端组件中运行；加了 ‘use client’ 后就不能再是 async.

客户端组件边界

// app/components/Counter.tsx
'use client';import { useState } from 'react';export default function Counter {
const = useState;return (
 setCount}>
至于点击次数，{count}

);}

Pain Point – 不小心把大量业务逻辑拖进客户端：

li>P1的观点是。在客户端入口导入了大量仅用于服务器的数据查询函数，引起 bundle 大幅膨胀。说到⚡️对策，保持 “服务器‑只” 模块与 “客户端‑只” 模块分离。用动态 import 按需加载。至于li>P2，在客户端组件里直接 async await 数据导致 SSR 优势失效。⚡️对策这方面，把数据拉到父级服务器组件，通过 props 向下传递；说起来，若必须在浏览器获取。用 useEffect + fetch 并接受加载状态。

原理/细节 :标记为客户端后该文件及其所有依赖都会被打包进浏览器；要谨慎控制体积并避免引用 Node 专属 API。说起来，

内置组件

一句话定义 :`` 替换 `

 import Link from 'next/link';import Image from 'next/image';import profilePic from '@/public/avatar.jpg';// 本地图片会自动获取宽高
export default function Header {
return (
关于


);}

Pain Point – 图片报错或布局抖动 ：

• P1 ：远程图片未在 `next.config.js` 中声明 remotePatterns，建立时报错。⚡️ 对策：统一在 config 中添加对应域名或使用 `loader:'custom'`。不过，
• P2 ：忘记设置 width/height 或 fill。导致 CLS 并触发 LCP 降级。⚡️ 对策：始终显式声明尺寸或使用 `fill` 并确保父容器定位。
• P3 ：滥用 `priority` 导致首屏资源过载。⚡️ 对策：仅给首屏关键图像加 `priority`，其余保持懒加载。

主要原理

静态渲染与动态渲染

一句话定义 :Next.js 在建立时尽量将页面预渲染成静态 HTML，一旦使用动态函数就退化为每次请求时生成页面。

 // 静态渲染——没有动态函数
export default async function Page {
const data = await fetch;return 

{data}
}
// 动态渲染——读取请求 Cookie
import { cookies } from 'next/headers';export default async function Page {
const cookieStore = await cookies;return 

{cookieStore.get?.value}
}
// 强制动态
export const dynamic = 'force-dynamic';说起来，

常见痛点 – 开发环境误判 静态 vs 动态 ：

• P1 : 在 `next dev` 下所有页面都是动态渲染。以为生产也一样，⚡️ 对策：执行 `next build && next start` 本地验证真实行为。
• P2 : 动态渲染导致数据库查询频繁，引起性能瓶颈。其实，⚡️ 对策：合理划分 SSG 与 SSR。并利用缓存或 ISR 控制频率。按理说，

数据缓存与重新验证

一句话定义 :Next.js 了原生 fetch 提供请求级缓存。你可以用 `revalidate` 设置多久更新一次或用 `revalidateTag` / `revalidatePath` 按需清除缓存。

 // 基于时间的重新验证。
每隔 X 秒更新
const res = await fetch('https://api.example.com/posts',{
至于next，{ revalidate: 60 },});// 基于标签的按需重新验证
import { revalidateTag } from 'next/cache';export async function updatePost {
// ... 更新数据库
revalidateTag;// 清除所有打了 posts 标签的缓存
}
// 带标签的 fetch 示例
const res = await fetch('https://api.example.com/posts'。{
再看next，{ tags: },});

Pain Point – 缓存失效不及时 ：

• P1 : 单纯使用 `revalidate` 导致内容更新延迟。⚡️ 对策：结合 webhook 调用 `revalidateTag` 实现即时刷新。
• P2 : 未配置相同 URL+options 导致同一请求未命中缓存，多次请求浪费资源。说起来，⚡️ 对策：统一封装 API 调用层，以相同选项发送请求。说起来，

实战模式

认证与路由保护

一句话定义 :`middleware.ts` 在请求进入路由前执行。适合做鉴权拦截、重定向、 请求头，且运行在 Edge Runtime。

 // middleware.ts
import { NextResponse } from 'next/server';import type { NextRequest } from 'next/server';export function middleware {
const token = request.cookies.get?.value，// 未登录且访问受保护方法 → 重定向到登录页
if ) {
return NextResponse.redirect);}
return NextResponse.next;}
export const config = {
matcher: '/dashboard/:path*',};

Pain Point – Edge 环境限制 ：

• P1 : 在中间件里误用了 Node fs 导致建立报错。⚡️ 对策：只使用 Edge‑兼容 API，如 Headers、Cookies 等。
• P2 : 中间件匹配过宽导致所有静态资源走 Edge 增加延迟。⚡️ 对策：精确配置 matcher，只针对业务方法拦截。

数据变更

一句话定义 :/ ‘use server’ 标记的异步函数可以直接从客户端调用。实现无缝的数据写入，无需单独创建 API 路由。

'use server';import { revalidatePath } from 'next/cache';import { db } from '@/lib/db';

export async function createPost { const title = formData.get as string;await db.post.create;revalidatePath;// 刷新列表页 }

/* 客户端表单 */ 'use client';import { createPost } from '@/app/actions/posts';

export function CreateForm { return (

创建<\/button>} <\/form>);}

Pain Point – CSRF 与返回值限制

• P1忘记返回可序列化的数据导致表单提交报错 ⚡️ 对策只能返回 JSON 或基本类型，不要返回类实例。

• P2在非

  场景下调用 Server Action 时缺少安全 token ⚡️ 对策自行加入 anti‑CSRF token 或改为表单方式提交。

DYNAMIC ROUTE STATIC GENERATION

"一句话定义": 给动态路由导出 generateStaticParams。让建立阶段预生成所有可能方法，实现 SSG。

tsx // app/posts//page.tsx export async function generateStaticParams { const posts = await fetch.n);return posts.map);}

export default async function PostPage { const post = await fetch.n);return {post.content};}

Pain Point – 建立时间爆炸 - P1 ：参数数量过大导致 CI 超时 ⚡️ 对策结合 ISR 或分批生成，仅保留热门方法。- P2 ：遗漏某些 slug 导致首次访问慢冷启动 ⚡️ 对策开启 fallback 并监控热点补齐。

export async function generateMetadata { const post = await fetch.slug}`).n);return { 说到title，post.title。description: post.excerpt,openGraph:{ images: },};}

Pain Point – 重复 Head 冲突 - P1 : 同时存在 static metadata 与 generateMetadata，两者冲突导致意外覆盖 ⚡️ 对策统一使用一种方式；若两者共存，以 generateMetadata 为准。其实，- P2 : 在自定义 中仍保留旧标签。引起 SEO 重复 ⚡️ 对策删除自定义 Head，只靠 Metadata API 管理 meta 信息。

// next.config.js 必须声明远程域名 module.exports={ images:{ remotePatterns:}};

Pitfalls - 没有 width/height 或 fill 会直接报错。- 使用 fill 时父元素必须定位，否则图片溢出。- 未配置 remotePatterns，在生产建立阶段图片调整会失败。

DATABASEURL=postgres://... # server‑only NEXTPUBLICAPIURL=https://api.example.com # 可前后端读取

Pain Points - 把敏感密钥误加 NEXTPUBLIC → 泄漏风险。- 客户端访问未加前缀变量得到 undefined → 报错。- 修改 env 后忘记重启 dev server → 配置未生效。

export default function SearchPage { return (

// app/search/SearchResults.tsx 'use client';import { useSearchParams } from 'next/navigation';

export default function SearchResults{ const searchParams=useSearchParams;const query=searchParams.get;return <>结果:{query};}

Pitfalls - 未加 Suspense 整页退化为 CSR 并出现 hydration mismatch。- searchParams 是只读对象，不可直接修改。需要 pushState 或 router.replace 实现跳转。- 客户端首次渲染时 query 与服务器侧不同，会产生水合错误 → 确保首次 SSR 已经读取相同 URL 参数。其实，

export default function DashboardLayout { const pathname=usePathname;const =useState;

return (

注意事项 - 布局内部不可直接读取 params，只能通过子页面或 client hooks 获取。其实，- 若布局用于全局播放器等跨页状态，可保留。否则请加 key 重置或改用 template. - 不要在 layout 中放大量业务逻辑，否则每次切换都重复执行影响性能。

---