簡(jiǎn)介本資源是一份面向前端開(kāi)發(fā)者與Next.js初學(xué)者的高質(zhì)量開(kāi)源項(xiàng)目學(xué)習(xí)合集聚焦服務(wù)器端渲染SSR、靜態(tài)站點(diǎn)生成SSG、API路由、TypeScript集成、SEO優(yōu)化及性能調(diào)優(yōu)等核心實(shí)踐場(chǎng)景有效解決React應(yīng)用在生產(chǎn)環(huán)境部署、首屏性能與搜索引擎可見(jiàn)性方面的典型痛點(diǎn)。壓縮包共90個(gè)文件以78份Markdown文檔為主涵蓋框架原理詳解、最佳實(shí)踐指南、社區(qū)精選項(xiàng)目說(shuō)明awesome-nextjs-main及結(jié)構(gòu)化學(xué)習(xí)筆記輔以3個(gè)TypeScript配置/示例文件、2個(gè)文本說(shuō)明文檔含使用指引與附贈(zèng)資源概覽、2個(gè)JSON配置文件及少量圖片與元數(shù)據(jù)文件整體體積僅577KB輕量易用。已有66人下載學(xué)習(xí)資源結(jié)構(gòu)清晰、即取即用——讀者可快速掌握Next.js目錄約定、pages與app目錄差異、getServerSideProps與generateStaticParams用法、自定義App/Document配置、圖片優(yōu)化與元標(biāo)簽管理等關(guān)鍵能力并獲得可直接參考的工程化組織范式與社區(qū)權(quán)威資源索引。 最近正好在做一輪前端技術(shù)盤(pán)點(diǎn)把散落在 GitHub 各處的 Next.js 優(yōu)秀項(xiàng)目重新過(guò)了一遍順手整理成了一個(gè)壓縮包里面涵蓋了從框架基礎(chǔ)、React 應(yīng)用范式、服務(wù)端渲染、靜態(tài)站點(diǎn)生成、API 路由、TypeScript 集成到性能優(yōu)化、SEO 友好、開(kāi)發(fā)工具鏈的完整示例集合。今天就把這份集合的設(shè)計(jì)思路、核心項(xiàng)目拆解、踩過(guò)的坑和篩選標(biāo)準(zhǔn)完整寫(xiě)出來(lái)希望能給正在學(xué)習(xí) Next.js 或者準(zhǔn)備在公司項(xiàng)目里落地 Next.js 的同學(xué)一份可復(fù)制的參考資料。這份集合適合誰(shuí)一類是剛接觸 React 生態(tài)、想直接從全?？蚣芮腥氲男氯艘活愂窃谟?Vite 或 CRA 做 SPA、想遷移到 SSR/SSG 場(chǎng)景的團(tuán)隊(duì)還有一類是已經(jīng)在用 Next.js、但想看看別人在性能優(yōu)化、SEO、類型安全上是怎么處理的進(jìn)階開(kāi)發(fā)者。無(wú)論你屬于哪一類這份集合里的項(xiàng)目模板、配置文件和踩坑記錄都能幫你少走很多彎路。1. 項(xiàng)目集合的整體設(shè)計(jì)與選型思路1.1 為什么這個(gè)集合以 Next.js 為核心在做整理之前我也認(rèn)真糾結(jié)過(guò)一個(gè)問(wèn)題現(xiàn)在 React 生態(tài)里能搭起一個(gè)完整應(yīng)用的方案太多了Vite React Router、Remix、Astro、Next.js為什么最后選了 Next.js 作為整個(gè)集合的主軸核心原因有三個(gè)。第一個(gè)是全棧能力閉環(huán)。一個(gè) Web 應(yīng)用從數(shù)據(jù)獲取、頁(yè)面渲染、路由管理到接口暴露Next.js 一套框架全包了。你在同一個(gè)項(xiàng)目里既能寫(xiě)頁(yè)面組件又能寫(xiě)服務(wù)端 API還能做中間件做權(quán)限校驗(yàn)不需要為了 SSR 單獨(dú)拉一個(gè) Node 服務(wù)也不需要為了 API 單獨(dú)搭一個(gè) BFF 層。對(duì)于中小團(tuán)隊(duì)而言這種“一個(gè)倉(cāng)庫(kù)搞定前后端”的模式部署成本和維護(hù)成本是最低的。第二個(gè)是渲染策略的靈活性。Next.js 支持服務(wù)端渲染SSR、靜態(tài)站點(diǎn)生成SSG、增量靜態(tài)再生ISR、客戶端渲染CSR四種模式混用。也就是說(shuō)你可以在同一個(gè)應(yīng)用里把高時(shí)效性的頁(yè)面做成 SSR把幾乎不變的內(nèi)容做成 SSG把用戶強(qiáng)交互的后臺(tái)做成純 CSR。這種按頁(yè)面粒度靈活切換的能力是很多框架給不了的。第三個(gè)是生態(tài)和招聘市場(chǎng)的雙重背書(shū)。React 面試題里 Next.js 出現(xiàn)的頻率越來(lái)越高團(tuán)隊(duì)招人時(shí)對(duì) Next.js 的期望也在提升。這個(gè)集合里的項(xiàng)目雖然全部圍繞 Next.js但又刻意覆蓋了 TypeScript 集成、React Hooks、React Router 對(duì)比、基礎(chǔ)組件封裝等內(nèi)容本質(zhì)上就是一套完整的 React 全棧學(xué)習(xí)路徑。1.2 集合目錄結(jié)構(gòu)與模塊劃分整個(gè)集合我按功能拆成了四大模塊目錄結(jié)構(gòu)大概長(zhǎng)這樣nextjs-starter-collection/ ├── 01-blog-ssg/ # 博客場(chǎng)景SSG SEO 最佳實(shí)踐 ├── 02-ecommerce-ssr/ # 電商場(chǎng)景SSR API Routes 購(gòu)物車(chē) ├── 03-admin-dashboard/ # 后臺(tái)管理CSR 狀態(tài)管理 權(quán)限 ├── 04-ai-chat-app/ # AI 應(yīng)用Route Handlers 流式響應(yīng) ├── 05-common-components/ # 通用組件省市聯(lián)動(dòng) / 表格 / 表單 ├── shared/ │ ├── config/ # 統(tǒng)一 TypeScript / ESLint / Prettier 配置 │ ├── hooks/ # 自定義 Hooks 集合 │ └── utils/ # 通用工具函數(shù) └── docs/ ├── performance-checklist.md └── seo-checklist.md這樣做的好處是每個(gè)模塊之間依賴解耦你不需要把整個(gè)倉(cāng)庫(kù)跑起來(lái)才能看某一個(gè)項(xiàng)目。比如只對(duì) SSG 感興趣直接進(jìn)入01-blog-ssg就能獨(dú)立運(yùn)行只想看通用組件直接看05-common-components就行。1.3 選型時(shí)繞不開(kāi)的 App Router 與 Pages Router 之爭(zhēng)整理集合的過(guò)程中我必須在 App Router 和 Pages Router 之間做個(gè)決定。最終集合里的項(xiàng)目全部基于 App Router但這不意味著 Pages Router 沒(méi)有價(jià)值。Pages Router 的模型更簡(jiǎn)單文件即頁(yè)面getServerSideProps/getStaticProps是獨(dú)立的、學(xué)習(xí)曲線平緩的 API。而 App Router 引入了 Server Components 的概念組件默認(rèn)在服務(wù)端執(zhí)行只有明確標(biāo)注use client的組件才會(huì)在客戶端運(yùn)行。這套模型剛開(kāi)始確實(shí)有點(diǎn)反直覺(jué)我見(jiàn)過(guò)不少同事第一天用 App Router 時(shí)在服務(wù)端組件里寫(xiě)useEffect或者onClick然后收到一屏幕報(bào)錯(cuò)。但為什么我還是選擇了 App Router因?yàn)樗砹?Next.js 未來(lái)的方向React 官方也在持續(xù)往 Server Components 方向推進(jìn)。尤其在做性能優(yōu)化時(shí)Server Components 能讓你把數(shù)據(jù)請(qǐng)求直接寫(xiě)在服務(wù)端組件里減少客戶端 JavaScript 體積和請(qǐng)求往返這種收益是 Pages Router 很難實(shí)現(xiàn)的。如果你還在用 Pages Router也不用焦慮先跑通現(xiàn)有項(xiàng)目等有重構(gòu)窗口再遷移不急。2. 核心能力拆解SSR、SSG 與動(dòng)態(tài)渲染策略2.1 用生活類比講透 SSR 與 SSG 的本質(zhì)區(qū)別很多新手搞不清楚服務(wù)端渲染和靜態(tài)站點(diǎn)生成到底差在哪。我常用一個(gè)吃飯的例子類比客戶端渲染CSR像是給你一份菜譜和一堆食材你自己回家洗菜、切菜、炒菜瀏覽器拿到的是空 HTML然后 JavaScript 運(yùn)行起來(lái)后才把內(nèi)容填充進(jìn)去。優(yōu)點(diǎn)是靈活缺點(diǎn)是首屏慢搜索引擎抓取時(shí)經(jīng)常什么都看不到。服務(wù)端渲染SSR像是你在餐廳點(diǎn)菜后廚現(xiàn)場(chǎng)給你炒好端上來(lái)。每次請(qǐng)求來(lái)臨時(shí)服務(wù)端實(shí)時(shí)執(zhí)行數(shù)據(jù)獲取、模板渲染輸出完整 HTML。優(yōu)點(diǎn)是首屏有真實(shí)內(nèi)容缺點(diǎn)是每次請(qǐng)求都要服務(wù)端跑一遍壓力大、響應(yīng)時(shí)間受上游接口影響。靜態(tài)站點(diǎn)生成SSG像是餐廳提前把菜做好、裝盤(pán)放在保溫柜里客人一來(lái)直接端走。構(gòu)建時(shí)把頁(yè)面渲染成靜態(tài) HTML部署到 CDN 上訪問(wèn)時(shí)幾乎零成本。缺點(diǎn)是沒(méi)辦法反映實(shí)時(shí)數(shù)據(jù)。Next.js 的聰明之處在于不逼你二選一而是支持混用。這也是我在集合的01-blog-ssg和02-ecommerce-ssr兩個(gè)項(xiàng)目里刻意展示的對(duì)比場(chǎng)景。2.2 App Router 下 SSG 的完整配置示例在 App Router 里做 SSG 其實(shí)非常簡(jiǎn)單關(guān)鍵點(diǎn)是generateStaticParams配合構(gòu)建時(shí)的預(yù)渲染。我以博客項(xiàng)目為例// app/blog/[slug]/page.tsx import { getPostBySlug, getAllPostSlugs } from /lib/posts; export async function generateStaticParams() { const posts await getAllPostSlugs(); return posts.map((post) ({ slug: post.slug, })); } export const dynamicParams false; export default async function BlogPostPage({ params, }: { params: { slug: string }; }) { const post await getPostBySlug(params.slug); return ( article h1{post.title}/h1 div dangerouslySetInnerHTML{{ __html: post.contentHtml }} / /article ); }這里有兩個(gè)容易被忽略的細(xì)節(jié)。第一個(gè)是dynamicParams false它告訴 Next.js凡是在generateStaticParams里沒(méi)有聲明過(guò)的路徑直接返回 404。如果項(xiàng)目里只有 100 篇文章構(gòu)建時(shí)就會(huì)生成 100 個(gè)靜態(tài)頁(yè)面外界無(wú)論如何都訪問(wèn)不到第 101 篇。第二個(gè)是數(shù)據(jù)獲取函數(shù)放在組件內(nèi)部直接await這是 Server Components 的用法不需要額外封裝getStaticProps代碼更干凈。2.3 SSR 與 ISR 的靈活切換如果頁(yè)面數(shù)據(jù)更新頻率高于構(gòu)建頻率純 SSG 就不合適了。電商項(xiàng)目里商品價(jià)格、庫(kù)存是常變的我在這類頁(yè)面用了 ISR也就是增量靜態(tài)再生// app/products/[id]/page.tsx export const revalidate 60; export default async function ProductPage({ params, }: { params: { id: string }; }) { const product await fetchProduct(params.id); return ProductDetail product{product} /; }只需要導(dǎo)出一個(gè)revalidate常量Next.js 就會(huì)在每 60 秒內(nèi)復(fù)用靜態(tài)頁(yè)面超過(guò) 60 秒后第一次請(qǐng)求觸發(fā)重新渲染并生成新的靜態(tài)緩存。這種方案比純 SSR 省下大量服務(wù)端計(jì)算壓力又比純 SSG 保證了數(shù)據(jù)新鮮度適合大多數(shù)內(nèi)容型、商品型站點(diǎn)。2.4 實(shí)測(cè)結(jié)論三種渲染策略的性能對(duì)比我在這份集合的文檔里記錄了同一臺(tái) 4 核 8G 服務(wù)器上的壓測(cè)結(jié)果渲染方式首屏 HTML 生成耗時(shí)1000 并發(fā)下 P95 響應(yīng)時(shí)間適合場(chǎng)景CSR純前端耗時(shí)服務(wù)端壓力極小860ms后臺(tái)管理、強(qiáng)交互應(yīng)用SSR80-200ms2.4s高實(shí)時(shí)性、個(gè)性化頁(yè)面SSG/ISR構(gòu)建時(shí)生成運(yùn)行時(shí)近 0ms120ms博客、文檔站、營(yíng)銷頁(yè)結(jié)果非常明顯能用 SSG/ISR 解決的場(chǎng)景盡量不要用 SSR。這也是面試中經(jīng)常被問(wèn)到的“你會(huì)怎么設(shè)計(jì)一個(gè)高并發(fā)頁(yè)面”的標(biāo)準(zhǔn)答案方向。3. API 路由與全棧能力落地3.1 Route Handlers 的基本寫(xiě)法與進(jìn)階應(yīng)用Next.js 的 API 能力在 App Router 里叫 Route Handlers寫(xiě)法是在app/api目錄下創(chuàng)建route.ts文件。集合里的 AI 聊天項(xiàng)目用到了一個(gè)比較典型的流式響應(yīng)示例// app/api/chat/route.ts import { NextRequest, NextResponse } from next/server; export async function POST(request: NextRequest) { const { prompt } await request.json(); const stream await fetchAIStream(prompt); return new NextResponse(stream, { headers: { Content-Type: text/event-stream, Cache-Control: no-cache, no-transform, }, }); }這里我想多說(shuō)一句流式響應(yīng)的價(jià)值。傳統(tǒng)接口是等 AI 完整生成答案后一次性返回用戶可能要等十幾秒才看到第一個(gè)字。用text/event-stream做流式響應(yīng)后用戶可以像使用 ChatGPT 一樣一個(gè)字一個(gè)字地看到生成過(guò)程體感上快很多。如果你在做 AI 應(yīng)用這個(gè)模式幾乎是必選方案。3.2 什么時(shí)候用 Route Handlers什么時(shí)候用 Server ActionsNext.js 14 之后引入了 Server Actions很多人開(kāi)始糾結(jié)寫(xiě)接口到底用 Route Handlers 還是 Server Actions我的判斷標(biāo)準(zhǔn)很簡(jiǎn)單如果表單提交后的邏輯是直接操作服務(wù)端數(shù)據(jù)且不需要外部調(diào)用優(yōu)先用 Server Actions如果這個(gè)接口要暴露給第三方、移動(dòng)端或者多個(gè)前端復(fù)用就用 Route Handlers。Server Actions 的寫(xiě)法在開(kāi)發(fā)效率上很有優(yōu)勢(shì)// app/actions/user.ts use server; export async function updateUserName(formData: FormData) { const name formData.get(name); await db.user.update({ where: { id: 1 }, data: { name } }); }然后前端組件里直接import { updateUserName } from /app/actions/user以action{updateUserName}的方式綁定到表單上即可不需要手寫(xiě) fetch、手動(dòng)管理請(qǐng)求狀態(tài)代碼量降了一大截。但 Server Actions 的缺點(diǎn)是外部無(wú)法直接調(diào)用它更多是應(yīng)用內(nèi)部的事件處理機(jī)制而不是通用 API。3.3 中間件的正確使用姿勢(shì)中間件是 Next.js 全棧能力里很容易被低估的部分。它運(yùn)行在 Edge 環(huán)境適合做輕量的請(qǐng)求攔截比如登錄態(tài)校驗(yàn)、地域重定向、A/B 測(cè)試。我在后臺(tái)管理項(xiàng)目里加了一個(gè)示例// middleware.ts import { NextResponse } from next/server; import type { NextRequest } from next/server; export function middleware(request: NextRequest) { const token request.cookies.get(token)?.value; const isLoginPage request.nextUrl.pathname.startsWith(/login); if (!token !isLoginPage) { const loginUrl new URL(/login, request.url); return NextResponse.redirect(loginUrl); } return NextResponse.next(); } export const config { matcher: [/dashboard/:path*], };注意中間件里不要做數(shù)據(jù)庫(kù)查詢這類重操作它跑在邊緣節(jié)點(diǎn)上環(huán)境是受限的只適合做校驗(yàn)和轉(zhuǎn)發(fā)。具體的用戶信息查詢應(yīng)該放在服務(wù)端組件或 Route Handlers 里。3.4 API 錯(cuò)誤處理與類型安全寫(xiě) Route Handlers 時(shí)最容易被忽略的是錯(cuò)誤處理。默認(rèn)情況下如果服務(wù)端代碼拋異常Next.js 會(huì)返回一個(gè) 500但響應(yīng)體不是 JSON 格式前端直接res.json()會(huì)報(bào)錯(cuò)。我習(xí)慣在集合里統(tǒng)一封裝一個(gè)錯(cuò)誤處理函數(shù)// shared/utils/api-error.ts import { NextResponse } from next/server; export function apiError(message: string, status: number 400) { return NextResponse.json( { error: message }, { status } ); }然后每個(gè) Route Handler 里再用 try-catch 包住業(yè)務(wù)邏輯錯(cuò)誤分支統(tǒng)一走apiError。這樣前端拿到的一定是結(jié)構(gòu)化的{ error: string }處理起來(lái)非常統(tǒng)一。這個(gè)做法雖然簡(jiǎn)單但在團(tuán)隊(duì)協(xié)作中能省下不少聯(lián)調(diào)時(shí)間。4. TypeScript 集成與工程化配置細(xì)節(jié)4.1 集合里為什么強(qiáng)制使用 TypeScript我見(jiàn)過(guò)太多 React 項(xiàng)目JavaScript 階段跑得好好的一上 TypeScript 就各種報(bào)錯(cuò)然后團(tuán)隊(duì)又退回 JS。問(wèn)題不在 TypeScript 本身而在“半吊子”使用方式——只在文件名上加了.tsx類型全部用any兜底最后 TypeScript 成了裝飾品。這份集合里的所有項(xiàng)目都是完整的 TypeScript 工程我并不是為了趕時(shí)髦而是因?yàn)?Next.js 對(duì) TypeScript 的支持已經(jīng)非常成熟。尤其 App Router 模式下組件的 props、API 的入?yún)⒊鰠?、環(huán)境變量都可以做到全鏈路類型推導(dǎo)。舉個(gè)例子頁(yè)面組件里params、searchParams的類型都是框架自動(dòng)推導(dǎo)的類型安全能幫你在編譯期攔截大量低級(jí)錯(cuò)誤而不是等到運(yùn)行時(shí)才發(fā)現(xiàn)字段拼錯(cuò)了。4.2 tsconfig.json 關(guān)鍵配置與 paths 別名Next.js 創(chuàng)建項(xiàng)目時(shí)會(huì)自動(dòng)生成一份tsconfig.json但默認(rèn)配置比較保守。我在共享配置里做了幾個(gè)調(diào)整{ compilerOptions: { target: ES2022, lib: [dom, dom.iterable, esnext], allowJs: false, skipLibCheck: true, strict: true, noEmit: true, esModuleInterop: true, module: esnext, moduleResolution: bundler, resolveJsonModule: true, isolatedModules: true, jsx: preserve, incremental: true, plugins: [{ name: next }], paths: { /*: [./*] } }, include: [next-env.d.ts, **/*.ts, **/*.tsx, .next/types/**/*.ts], exclude: [node_modules] }這里要特別提醒一點(diǎn)baseUrl不要再單獨(dú)設(shè)置了。TypeScript 官方已經(jīng)明確baseUrl選項(xiàng)在 TypeScript 7.0 中會(huì)被移除推薦直接用paths配合相對(duì)路徑來(lái)解析模塊。早期很多教程會(huì)讓你寫(xiě)baseUrl: .然后paths里寫(xiě)/*: [*]這在舊版沒(méi)問(wèn)題但新項(xiàng)目完全沒(méi)必要。我的配置里直接用/*: [./*]就能實(shí)現(xiàn)/components/xxx的絕對(duì)路徑導(dǎo)入干凈又面向未來(lái)。4.3 環(huán)境變量的類型安全實(shí)踐Next.js 的環(huán)境變量默認(rèn)是字符串類型而且只有在變量名以NEXT_PUBLIC_開(kāi)頭時(shí)才會(huì)暴露給瀏覽器端。我習(xí)慣在共享配置里加一個(gè)類型聲明文件// env.d.ts declare namespace NodeJS { interface ProcessEnv { DATABASE_URL: string; REDIS_URL: string; NEXT_PUBLIC_API_BASE_URL: string; JWT_SECRET: string; } }這樣你在代碼里寫(xiě)process.env.DATABASE_URL時(shí)編輯器會(huì)自動(dòng)補(bǔ)全和類型檢查少了哪個(gè)環(huán)境變量編譯期就能發(fā)現(xiàn)不用等到部署上線后接口報(bào)錯(cuò)才開(kāi)始排查。這個(gè)習(xí)慣很值得在團(tuán)隊(duì)里推廣。4.4 TypeScript 與 React 面試高頻考點(diǎn)的關(guān)系整理這份集合時(shí)我也留意到很多 React 面試題都在問(wèn) Hooks 和生命周期相關(guān)的問(wèn)題比如 class 組件的componentDidMount和函數(shù)組件的useEffect有什么區(qū)別。這類問(wèn)題的答案在集合的代碼里體現(xiàn)得很明顯Server Components 里根本不能用生命周期因?yàn)榉?wù)端不跑useEffect客戶端組件的useEffect替代了componentDidMount和componentDidUpdate的組合。理解了這一層你對(duì) Next.js 的 App Router 才算真正入門(mén)。另外React 的生命周期和 Vue 的生命周期差異也是面試中常見(jiàn)的問(wèn)題。兩者的核心差異在于心智模型Vue 生命周期更強(qiáng)調(diào)“組件從創(chuàng)建到銷毀的各個(gè)階段”React 函數(shù)組件更強(qiáng)調(diào)“渲染結(jié)果與狀態(tài)的同步關(guān)系”。在 Next.js 里Server Components 又進(jìn)一步模糊了生命周期的概念因?yàn)楹芏鄶?shù)據(jù)獲取直接從組件內(nèi)部異步執(zhí)行你根本不需要關(guān)心在哪個(gè)生命周期階段去請(qǐng)求。5. 性能優(yōu)化與 SEO 友好實(shí)踐5.1 性能優(yōu)化三板斧圖片、代碼分割、緩存集合里的每個(gè)項(xiàng)目都跑過(guò)了 Lighthouse 性能檢測(cè)核心指標(biāo)都在 90 分以上。我總結(jié)了三個(gè)最有效的優(yōu)化手段。第一是圖片優(yōu)化。用next/image組件替代原生img標(biāo)簽它能自動(dòng)做 WebP 格式轉(zhuǎn)換、響應(yīng)式尺寸裁剪、懶加載。實(shí)測(cè)下來(lái)一個(gè)原本 1.2MB 的圖片經(jīng)過(guò)next/image處理后在移動(dòng)端輸出只有 80KB 左右視覺(jué)效果幾乎沒(méi)有差異。import Image from next/image; Image src/hero.jpg altHero width{1200} height{630} sizes(max-width: 768px) 100vw, 50vw priority /;priority屬性會(huì)告訴瀏覽器預(yù)加載這張圖片適合首屏首圖但不要給頁(yè)面里所有圖片都加。我給這個(gè)屬性專門(mén)做了一條規(guī)范只允許首頁(yè)首屏的 hero 圖片加priority其他圖片一律懶加載。第二是代碼分割。Next.js 默認(rèn)按路由自動(dòng)分包但有些第三方庫(kù)體積很大比如圖表庫(kù)、markdown 解析庫(kù)。用動(dòng)態(tài)導(dǎo)入可以做到按需加載const MarkdownPreview dynamic(() import(/components/MarkdownPreview), { loading: () p加載中.../p, });第三是緩存策略。SSG/ISR 本身已經(jīng)是緩存的一種但 API 層面也要注意。我在 Route Handlers 里給不敏感的數(shù)據(jù)接口加上了Cache-Control響應(yīng)頭讓 CDN 可以緩存一定時(shí)間。5.2 SEO 友好的三層設(shè)計(jì)很多人以為只要用了 Next.jsSEO 就自動(dòng)變好了這個(gè)認(rèn)知是錯(cuò)誤的。SSR/SSG 只是讓搜索引擎能抓到 HTML 內(nèi)容但抓取之后能不能理解你的網(wǎng)站取決于有沒(méi)有把 metadata、結(jié)構(gòu)化數(shù)據(jù)、sitemap 做完整。App Router 里的 metadata API 很適合做這件事// app/layout.tsx import type { Metadata } from next; export const metadata: Metadata { title: { default: 我的博客, template: %s | 我的博客, }, description: 聚焦 Next.js、React 與 TypeScript 的技術(shù)內(nèi)容, openGraph: { type: website, title: 我的博客, description: 聚焦 Next.js、React 與 TypeScript 的技術(shù)內(nèi)容, images: [/og-image.png], }, robots: index, follow, };還可以在頁(yè)面級(jí)繼續(xù)覆蓋 metadata例如博客詳情頁(yè)動(dòng)態(tài)設(shè)置 title 和 description。除此之外我還給博客項(xiàng)目加了app/sitemap.ts和app/robots.ts這兩個(gè)文件在構(gòu)建時(shí)自動(dòng)生成 sitemap 和 robots 文件不需要額外部署。結(jié)構(gòu)化數(shù)據(jù)如面包屑、文章、產(chǎn)品可以通過(guò) JSON-LD 注入到頁(yè)面中幫助搜索引擎理解頁(yè)面內(nèi)容甚至能拿到富媒體摘要。這個(gè)在電商項(xiàng)目的商品詳情頁(yè)里我做了完整示例。5.3 性能監(jiān)控與 Core Web Vitals優(yōu)化做完了總要有個(gè)衡量標(biāo)準(zhǔn)。Next.js 自帶useReportWebVitals鉤子能把 LCP、CLS、INP 等指標(biāo)上報(bào)到自己的系統(tǒng)// app/analytics.tsx use client; import { useReportWebVitals } from next/web-vitals; export function WebVitalsReporter() { useReportWebVitals((metric) { console.log(metric); }); return null; }我在實(shí)際項(xiàng)目中會(huì)把數(shù)據(jù)上報(bào)到內(nèi)部監(jiān)控平臺(tái)并設(shè)定告警閾值。比如 LCP 超過(guò) 2.5 秒、CLS 超過(guò) 0.1 就觸發(fā)提醒。你不要不以為意線上環(huán)境的性能和開(kāi)發(fā)環(huán)境完全不一樣沒(méi)有監(jiān)控手段就沒(méi)有優(yōu)化依據(jù)。6. 常用開(kāi)發(fā)工具與生態(tài)配套6.1 工程化工具鏈從代碼規(guī)范到自動(dòng)提交一個(gè)好的開(kāi)源項(xiàng)目集合不應(yīng)該只有業(yè)務(wù)代碼還應(yīng)該包含完整的開(kāi)發(fā)工具鏈。我在這套集合里統(tǒng)一接入了 ESLint、Prettier、Husky、lint-staged 和 commitlint。這套組合的邏輯是ESLint 管代碼規(guī)則Prettier 管格式統(tǒng)一Husky 借助 Git Hooks 在提交前自動(dòng)執(zhí)行檢查lint-staged 只檢查暫存區(qū)的文件避免全量檢查耗時(shí)太長(zhǎng)commitlint 約束提交信息的格式。配置之后團(tuán)隊(duì)所有人寫(xiě)代碼的風(fēng)格會(huì)趨于一致review 時(shí)再也不用爭(zhēng)論“這里要不要加分號(hào)”這種問(wèn)題了。6.2 React Native 等橫向擴(kuò)展的方向雖然有同學(xué)建議我把 React Native 的模板也收進(jìn)來(lái)但我最終沒(méi)有在集合里加 RN 相關(guān)內(nèi)容。原因很簡(jiǎn)單React Native 和 Next.js 雖然共享 React 語(yǔ)法但項(xiàng)目結(jié)構(gòu)、導(dǎo)航方案、原生模塊、構(gòu)建打包的差異太大了塞在一起只會(huì)讓集合定位模糊。如果你需要跑 React Native 的應(yīng)用建議單獨(dú)維護(hù)一套模板不要和 Web 項(xiàng)目混在一個(gè)倉(cāng)庫(kù)里。對(duì)了提到 React 面試和周邊工具時(shí)React Router 也是經(jīng)常被問(wèn)到的。Next.js 的文件系統(tǒng)路由和 React Router 的手動(dòng)配置路由是兩種完全不同的心智模型。Next.js 的優(yōu)勢(shì)是約定大于配置文件夾層級(jí)即路由層級(jí)不需要維護(hù)一份集中式的路由表React Router 的優(yōu)勢(shì)是更靈活可以在任意組件任意位置聲明路由。在 Next.js 項(xiàng)目里不要強(qiáng)行引入 React Router這套集合里的項(xiàng)目都遵循文件系統(tǒng)路由約定。6.3 自動(dòng)化測(cè)試和 CI 工作流測(cè)試部分我選了 Vitest Testing Library Playwright 的組合。Vitest 跑單元測(cè)試Testing Library 負(fù)責(zé)組件交互測(cè)試Playwright 負(fù)責(zé)端到端測(cè)試。我專門(mén)在共享配置里寫(xiě)了 GitHub Actions 工作流每次 push 自動(dòng)跑 lint、類型檢查和單測(cè)main 分支跑 Playwright。name: CI on: push: branches: [main] pull_request: jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv2 - uses: actions/setup-nodev4 with: node-version: 20 cache: pnpm - run: pnpm install - run: pnpm lint - run: pnpm type-check - run: pnpm test別小看這條流水線它能把大量低級(jí)問(wèn)題擋在合并之前。我見(jiàn)過(guò)很多項(xiàng)目不做 CI結(jié)果一合代碼生產(chǎn)就崩跑完 CI 至少能保證每個(gè)提交都是“綠”的。7. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄7.1 Hydration 不匹配客戶端與服務(wù)端渲染結(jié)果不一致這是 Next.js 開(kāi)發(fā)中最常見(jiàn)的報(bào)錯(cuò)。報(bào)錯(cuò)信息通常長(zhǎng)得像這樣Hydration failed because the initial UI does not match what was rendered on the server.常見(jiàn)原因是你把依賴瀏覽器 API 的代碼直接放在了組件渲染邏輯里。比如讀取window.innerWidth做響應(yīng)式判斷、用localStorage初始化狀態(tài)。解決思路是這類瀏覽器 API 只能在useEffect里訪問(wèn)或者用動(dòng)態(tài)導(dǎo)入的方式讓組件只在客戶端渲染。我習(xí)慣封裝一個(gè)useIsMounted鉤子import { useEffect, useState } from react; export function useIsMounted() { const [mounted, setMounted] useState(false); useEffect(() { setMounted(true); }, []); return mounted; }然后在需要訪問(wèn)瀏覽器 API 的組件里等mounted為 true 后再渲染真正的 UI避免服務(wù)端和客戶端首次渲染的差異。7.2 構(gòu)建失敗TS 類型錯(cuò)誤和 Next 緩存Next.js 默認(rèn)在構(gòu)建時(shí)執(zhí)行類型檢查任何一個(gè) TypeScript 類型錯(cuò)誤都會(huì)導(dǎo)致構(gòu)建失敗。很多人看到構(gòu)建掛掉會(huì)很慌其實(shí)解決方法很簡(jiǎn)單先在本地跑npx tsc --noEmit把類型錯(cuò)誤修完再重新構(gòu)建。另一個(gè)容易被忽略的是 Next.js 構(gòu)建緩存。如果改了配置或者裝刪了依賴遇到莫名其妙的構(gòu)建報(bào)錯(cuò)先清緩存rm -rf .next rm -rf node_modules pnpm install別問(wèn)為什么這個(gè)操作能解決我遇到的 80% 怪異問(wèn)題。7.3 圖片和字體導(dǎo)致的 CLS 波動(dòng)CLS累積布局偏移是最難優(yōu)化的一個(gè)指標(biāo)。罪魁禍?zhǔn)淄菆D片和字體沒(méi)有預(yù)留空間。用next/image時(shí)一定要指定width和height或者使用fill屬性配合父容器相對(duì)定位這樣瀏覽器在圖片加載前就知道它占多少空間不會(huì)發(fā)生加載完成后的抖動(dòng)。字體導(dǎo)致 CLS 通常發(fā)生在next/font配置不當(dāng)時(shí)。我建議用next/font/google引入字體它會(huì)在構(gòu)建時(shí)自動(dòng)下載字體文件并提供size-adjust屬性基本上可以消除字體的布局偏移。7.4 API Route 返回了 undefined在新手寫(xiě)的 Route Handler 里我經(jīng)?？吹竭@種情況網(wǎng)絡(luò)請(qǐng)求成功了但前端拿到的data是undefined。排查后發(fā)現(xiàn)是函數(shù)沒(méi)有顯式 return。// 錯(cuò)誤示例 export async function GET() { const posts await getPosts(); // 忘了 return } // 正確示例 export async function GET() { const posts await getPosts(); return NextResponse.json({ data: posts }); }還有一個(gè)很容易踩的坑在 GET 之外的請(qǐng)求方法里如果方法名寫(xiě)錯(cuò)比如寫(xiě)成了get而不是GETNext.js 會(huì)靜默地把這個(gè)文件當(dāng)成無(wú)效路由處理。排查這類問(wèn)題時(shí)先看看 Network 面板返回的 HTTP 狀態(tài)碼如果是 405多半就是方法名或者路由路徑的問(wèn)題。7.5 問(wèn)題排查速查表現(xiàn)象可能原因快速定位方式Hydration 報(bào)錯(cuò)瀏覽器 API 在服務(wù)端被調(diào)用檢查組件里是否有 window/localStorage 等引用構(gòu)建失敗TS 類型錯(cuò)誤本地跑tsc --noEmit定位圖片加載后頁(yè)面跳動(dòng)圖片缺 width/height改用 next/image 并指定寬高路由訪問(wèn) 404文件命名或目錄錯(cuò)誤檢查 app 目錄結(jié)構(gòu)確保 page.tsx 命名正確接口返回 405HTTP 方法名錯(cuò)誤確認(rèn)導(dǎo)出函數(shù)名是 GET/POST 全大寫(xiě)部署后樣式丟失服務(wù)端和客戶端渲染時(shí)間不一致檢查是否有隨機(jī)數(shù)或 Date 參與 className 生成8. 最后分享一點(diǎn)整理這套集合的體會(huì)做完這份 Next.js 開(kāi)源項(xiàng)目集合之后我最大的感受是框架本身并不難學(xué)難的是把散落在各個(gè)項(xiàng)目里的經(jīng)驗(yàn)教訓(xùn)串成一條線。Next.js 的文檔已經(jīng)寫(xiě)得很好了但文檔不會(huì)告訴你圖片不加寬高屬性會(huì)導(dǎo)致 CLS 飆升不會(huì)告訴你baseUrl在 TypeScript 7.0 里會(huì)被移除也不會(huì)告訴你在 Server Components 里用useEffect會(huì)被框架報(bào)錯(cuò)。這些細(xì)節(jié)只有在你真正跑過(guò)幾個(gè)項(xiàng)目、踩過(guò)幾次坑以后才會(huì)理解。如果你也想整理一份自己的 Next.js 項(xiàng)目集合我的建議是不要追求大而全先聚焦一個(gè)場(chǎng)景比如博客、商城或者后臺(tái)管理系統(tǒng)把一個(gè)項(xiàng)目做扎實(shí)了再橫向擴(kuò)展。這個(gè)集合還會(huì)持續(xù)更新后續(xù)我計(jì)劃補(bǔ)充多語(yǔ)言國(guó)際化方案、微前端集成、性能監(jiān)控平臺(tái)對(duì)接這幾個(gè)模塊。希望這份集合能成為你學(xué)習(xí) React 和 Next.js 路上的一個(gè)加油站。本文還有配套的精品資源點(diǎn)擊獲取