Next.js 全栈框架

Next.js 是由 Vercel 打造的生产级 React 全栈框架，是目前 React 生态中最流行、功能最完整的全栈 Web 开发基础底座。它深度整合了 React 19、Turbopack、React Server Components、Partial Prerendering 等前沿技术，提供从静态站点到企业级 SaaS 的全场景解决方案。

一、 基本信息

二、 版本历史与 2026 年现状

2026 年核心趋势

1. App Router 成为绝对主流：Pages Router 已进入维护模式，新项目默认采用 App Router。
2. Turbopack 默认全阶段启用：Webpack 成为可选回退，Rust 工具链在大型项目中优势显著。
3. Partial Prerendering 重塑渲染策略：不再需要在 SSG 与 SSR 之间做非此即彼的选择。
4. Server Components 生态成熟：server-only / client-only 包、cache 函数、next/after 等原生能力成为标准实践。
5. Vercel 平台深度绑定：从部署、预览、边缘函数、分析到 AI SDK，Next.js 已成为 Vercel 生态的核心基石。

三、 技术定位与简介

Next.js 的诞生是为了解决 React 客户端单页应用 (SPA) 的三大致命痛点：

1. SEO (搜索引擎优化) 极其不友好：客户端渲染只能给爬虫提供一个近乎空白的 HTML 外壳。
2. 首屏白屏时间长 (LCP 慢)：需要下载并执行庞大的 JavaScript 资源束才能开始渲染页面。
3. 数据获取瀑布流与安全隐私问题：前端直接请求数据库和密钥具有严重的安全风险。

Next.js 深度集成了 React 核心团队的最新学术成果 (如 React Server Components、React Suspense、Server Actions 等)，打破了前端与后端的物理边界，通过统一的组件开发体验、全自动的混合渲染机制、极致的资源优化和极速的打包工具链 (Turbopack)，为开发者提供了一套开箱即用、涵盖从单页应用到企业级多租户 SaaS 系统的全能解决方案。

四、 快速上手安装说明

1. 初始化项目

在终端中执行以下命令以创建 Next.js 项目。脚手架会自动引导你进行选项配置：

pnpm create next-app@latest

脚手架选项推荐配置 (2026 规范)：

• Project name: my-next-app
• TypeScript: Yes (强制开启，提供极强的类型安全性)
• ESLint: Yes (建议，配合项目级 Linter)
• Tailwind CSS: Yes (现代 UI 排版首选)
• Src directory: Yes (将源代码隔离在 src/ 下，使项目结构更加清晰)
• App Router: Yes (推荐开启，全新嵌套布局路由系统，Pages Router 已标记为 Legacy)
• Turbopack: Yes (开发模式下默认启用 Rust 极速打包引擎)
• Customize default import alias: Yes (推荐设置为 @/*，方便路径导入)

2. 标准物理目录结构 (App Router)

my-next-app/
├── src/
│   ├── app/                    # App Router 根路由目录
│   │   ├── layout.tsx          # 全局持久布局 (Root Layout)
│   │   ├── page.tsx            # 根路径页面 (/)
│   │   ├── loading.tsx         # 路由级的流式 Suspense 骨架屏
│   │   ├── error.tsx           # 路由级的运行时错误边界
│   │   ├── not-found.tsx       # 全局 404 页面
│   │   ├── global.css          # 全局样式表
│   │   ├── sitemap.ts          # 动态站点地图
│   │   ├── robots.ts           # 动态 robots.txt
│   │   └── dashboard/          # 子路由示例 (/dashboard)
│   │       ├── layout.tsx      # 仪表盘嵌套布局
│   │       ├── page.tsx        # 仪表盘页面
│   │       ├── loading.tsx     # 仪表盘级骨架屏
│   │       └── error.tsx       # 仪表盘级错误边界
│   ├── components/             # 应用级共享展示组件
│   ├── features/               # 业务功能模块 (按领域拆分)
│   ├── lib/                    # 工具类、通用 SDK 封装
│   ├── api/                    # 服务端模块/Server Actions 归类目录
│   └── i18n/                   # 国际化配置 (如 next-intl)
├── public/                     # 静态资源存放地 (图片、字体等)
├── next.config.ts              # Next.js 核心配置文件 (推荐 TypeScript 版本)
├── package.json
├── tsconfig.json
└── biome.json                  # 2026 年推荐 Biome 替代 ESLint/Prettier

3. next.config.ts 推荐配置

// next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  // 启用 React Compiler (Next.js 16+)
  experimental: {
    reactCompiler: true,
    // 对 lucide-react 等大型库进行按需导入优化
    optimizePackageImports: ['lucide-react', '@repo/ui']
  },
  // Monorepo 共享 UI 包需要转译
  transpilePackages: ['@repo/ui'],
  // 图片远程域名白名单
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'cdn.example.com' }
    ]
  }
}
 
export default nextConfig

4. 工程核心开发命令

pnpm dev      # 启动开发服务器，默认启用 Turbopack，监听 http://localhost:3000
pnpm build    # 生产环境静态分析与打包构建
pnpm start    # 生产环境冷启动
pnpm lint     # 运行 Linter 检查

五、 核心特性

1. 物理文件系统路由 (App Router)

基于 src/app/ 目录下的文件夹和文件。只要创建了 src/app/blog/page.tsx，就会自动映射出 /blog 路由。

• 嵌套布局 (Nested Layouts)：子路由页面会嵌套在父级 layout.tsx 中，切换子路由时父布局状态会被完整保留，且不重新渲染。
• 路由组 (Route Groups (marketing))：仅用于逻辑分组和共享不同布局，不污染实际 URL。
• 动态分段 (Dynamic Segments [id])：通过参数化捕获 URL，例如 /blog/[id]。
• 并行路由 (Parallel Routes @modal)：允许在一个布局中同时且独立渲染多个页面。
• 拦截路由 (Intercepted Routes (.)photo)：在当前页面上下文中加载另一个路由的内容，常用于模态框图片查看器。
• 路由级错误边界 (error.tsx) 与 404 (not-found.tsx)：每个路由段可独立定义错误处理与缺页状态，无需全局 try-catch。

2. 混合组件心智模型 — Server vs Client Components

Next.js 15+ 默认组件均为 React Server Components (RSC)：

• React Server Components (RSC)：
  • 零客户端运行时 JS：所有依赖库和渲染计算仅在服务端发生，传输到客户端的只是纯净的 HTML。
  • 直连后端：可以直接进行数据库查询、读取服务端文件、调用微服务 API。
  • 安全性强：数据库密码、私钥等信息绝不泄漏给浏览器。
• Client Components (CC)：
  • 在文件顶部声明 "use client"。
  • 支持 React Hooks、状态管理以及 DOM 事件监听。
  • 同样会在服务端预渲染生成 HTML，实现极速首屏呈现，随后在浏览器进行“水合” (Hydration)。

3. Server Actions (服务端动作)

Server Actions 是直连前后端的 RPC 原生机制。通过在文件顶部标记 "use server"，客户端组件可直接调用服务端函数：

// src/app/actions.ts
'use server'
 
import { revalidatePath } from 'next/cache'
 
export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  const content = formData.get('content') as string
 
  await db.post.create({ data: { title, content } })
 
  // 数据变更后使相关缓存失效
  revalidatePath('/posts')
}

// src/app/posts/new/page.tsx
import { createPost } from '@/app/actions'
 
export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <textarea name="content" required />
      <button type="submit">发布</button>
    </form>
  )
}

4. Turbopack 构建引擎

Vercel 采用 Rust 语言深度定制的下一代打包系统，致力于取代 Webpack：

• 在中大型项目中，热更新重载 (HMR) 速度提升 10 倍以上。
• Next.js 15+ 开发模式默认启用，Next.js 16 已拓展至全阶段构建，带来闪电般的冷启动和重载速度。

5. Middleware 中间件

基于 Edge Runtime 的请求拦截层，可在请求到达页面或 API 路由前执行逻辑：

• 认证鉴权与重定向。
• A/B 测试与灰度发布。
• 地理围栏、IP 限制、机器人拦截。
• 多语言前缀重定向与 SEO 规范化。

// src/middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  const token = request.cookies.get('session-token')
 
  // 未登录用户访问 /dashboard 时重定向到登录页
  if (request.nextUrl.pathname.startsWith('/dashboard') && !token) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
 
  return NextResponse.next()
}
 
export const config = {
  matcher: ['/dashboard/:path*']
}

6. 图片与字体优化

• next/image：自动提供 WebP/AVIF 格式转换、响应式尺寸、懒加载、占位 blur、防止布局偏移 (CLS)。
• next/font：自动下载并优化 Google/本地字体，消除网络请求瀑布与布局偏移，支持 CSS font-display: swap 自动注入。

7. Metadata API 与 SEO

通过 metadata 对象和 generateMetadata 函数声明式管理页面元数据：

// src/app/blog/[slug]/page.tsx
import type { Metadata } from 'next'
 
export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
  const { slug } = await params
  const post = await fetchPost(slug)
 
  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      images: [{ url: post.coverImage }]
    }
  }
}

8. 增量静态再生 (ISR) 与缓存控制

• ISR：构建时生成静态页面，运行期间按需重新生成，无需全量重建。
• 动态段配置：通过 export const revalidate = 60 或 export const dynamic = 'force-dynamic' 精确控制每个路由的缓存行为。
• 手动缓存失效：revalidatePath 与 revalidateTag 在 Server Actions 或 Route Handlers 中触发。

六、 适用场景

1. 黄金适用场景 (Highly Recommended)

• 内容聚合与媒体站 (Blogs & Media)：高频更新、需要极致的首屏加载与极佳的 SEO。通过 SSG + ISR 保持极速体验。
• 跨国企业官网与营销落地页 (Landing Pages)：内置 next/image、next/font 与强大的国际化生态 (next-intl)，带来无布局偏移 (CLS) 的视觉盛宴。
• 电商平台 (Storefront)：混合 PPR 特性，静态外壳瞬间呈现，用户个性化价格与购物车异步流式载入，结合 CDN 边缘部署将转化率提升到极致。
• 全栈式 SaaS 软件/应用：前后端工程一体化，使用 Server Actions 极其适合数据变更密集的操作。
• AI 驱动的生成式应用：配合 Vercel AI SDK 与 RSC，流式输出动态填充 UI 岛屿。

2. 局限适用场景 (Not Ideal)

• 纯后台管理系统 (Dashboard-only Apps)：若应用 100% 被登录鉴权保护，且无任何 SEO 要求、不敏感于初始首屏 FCP。纯客户端 SPA (如 Vite + Vue3 / React SPA) 的路由心智更纯粹，无需承受 RSC 的数据序列化边界心智成本。

七、 技术亮点

1. Partial Prerendering (PPR，部分预渲染)

PPR 改变了传统的“要么整页静态(SSG)，要么整页动态(SSR)”的粗放思维：

• 静态外壳：Next.js 在构建阶段将页面中的静态节点 (如导航栏、空白框) 预渲染成 HTML。
• 动态岛屿：对于动态的、受 Suspense 保护的区域 (如个性化推荐、购物车)，服务端在页面响应时立即下发静态外壳，并在同一 TCP 连接中将动态数据“流式流出 (Streaming)”，随后动态填充对应的组件位置。

2. next/after (请求后非阻塞运行)

由于 Node.js 单线程模型，在传统 HTTP 请求处理过程中，诸如“记录审计日志、推送分析事件、清理多余临时文件、刷新缓存”等副作用会延长响应时间，让用户等待。 next/after 允许开发者在发送完响应后，安排后台副作用任务的安全执行，优雅免去了引入重量级消息队列 (Message Queue) 的成本。

import { after } from 'next/server'
 
export async function POST(request: Request) {
  const result = await updateDatabase(request)
 
  after(async () => {
    await sendAuditLog(result)
    await analytics.track('order_created')
  })
 
  return Response.json(result)
}

3. App Router 的嵌套与高级路由能力

App Router 提供了前所未有的路由灵活性：

• 嵌套布局：父布局持久化，子路由切换不破坏父级状态。
• 并行路由：一个布局中同时渲染多个独立页面，适用于复杂后台仪表盘的并排面板。
• 拦截路由：在保留当前路由上下文的同时展示目标路由内容，常用于图片/商品详情模态框。

4. 缓存策略的可预测性升级

Next.js 15 对缓存策略做了重大调整：

• fetch 请求默认不再缓存。
• 客户端路由缓存默认关闭。
• Route Handler 默认不缓存。 这些变化让行为更可预测，开发者需要显式选择缓存策略，而非默认缓存后踩坑。

5. 最完善的生态网络效应

Next.js 拥有 React 框架中最完善的生态系统：Vercel 一键部署、v0 AI UI 生成、Prisma/Auth.js 全栈方案、丰富的 starter 模板。其生态优势与 Vercel 的商业支持使其地位在 2026 年依然稳固。

八、 核心概念与架构

1. 混合组件树结构与序列化边界 (Serialization Boundary)

在 Next.js 的 App Router 架构中，服务器组件 (RSC) 与客户端组件 (CC) 交织共存，组成一棵混合组件树。

• RSC 可以作为 Client Component 的子级：但不能直接在客户端组件文件中 import 服务端组件。需要通过 children 插槽或 props 的形式，在服务端将 RSC 注入给客户端组件。
• 序列化边界：当数据从 RSC 跨越边界传递到 CC 时，必须可以被 JSON 序列化。不能传递函数、复杂类实例 (如 Prisma Model 实例)、Symbol、未处理的 Map/Set，必须先转换为基础对象或原始类型。

graph TD
  Root[Root Layout: RSC] --> Nav[Navbar: CC]
  Root --> Content[Page Content: RSC]
  Nav --> Button[ThemeButton: CC]
  Content --> Product[ProductDetail: RSC]
  Product --> Tabs[TabContainer: CC]
  Tabs --> Slot[RSC passed as Children]

2. 缓存体系结构

Next.js 设计了四层级联缓存，旨在提供极致渲染性能，但心智负担较高：

1. Request Memoization (请求记忆化)：在单个服务器渲染周期内，对相同 URL 的 fetch 动作自动去重 (React.cache)。
2. Data Cache (数据缓存)：跨请求的持久化服务器缓存。支持 revalidateTag 或 revalidatePath 手动/增量失效。
3. Full Route Cache (全页渲染缓存)：在构建时将整个路由的 HTML 和 RSC 负载在服务端缓存。
4. Router Cache (客户端路由缓存)：在浏览器运行期间缓存已加载的路由段。

Next.js 15+ 重大更新：fetch 缓存、客户端路由缓存默认改为 默认不缓存 (No cache by default)，提升可预测性。

3. 数据流与请求生命周期

graph LR
  Request[HTTP Request] --> Middleware[Edge Middleware]
  Middleware --> Layout[RSC Layout]
  Layout --> Page[RSC Page]
  Page --> Suspense[Suspense Boundaries]
  Suspense --> Streaming[Streaming HTML + RSC Payload]
  Streaming --> Hydration[Client Hydration]
  Hydration --> Interactivity[Interactive Client Components]

九、 技术局限与边界

1. 自托管摩擦 (Self-hosting Friction)： Next.js 的许多高级特性 (如 Middleware 拦截、Image 动态优化、CDN 静态边缘分发) 是针对 Vercel 生态深度定制的。在标准 Docker / AWS ECS 传统服务器中托管时，由于缺乏边缘计算节点协同，Image 优化会消耗极高 CPU，且 Middleware 会带来明显运行时延迟。通常需要借助 OpenNext 等社区框架进行底座适配。

2. 陡峭的心智曲线与调试难度： 在混合树架构中，新手极易混淆组件是在“服务端执行”还是“客户端执行”。在 RSC 中意外引入浏览器 API (如 window.sessionStorage)，或在 Server Actions 中由于打包问题泄露不应导出的代码时，报错信息往往令人费解。

3. 缓存过度设计的包袱： Next.js 13/14 中的强缓存策略曾让大量开发者陷入“本地开发完好、上线内容死活不更新”的困局。虽然 Next.js 15/16 放宽了默认限制，但其四层级联缓存的心智复杂度依然是全行业首屈一指。

4. Vercel 平台锁定风险： 虽然 Next.js 是开源框架，但部分最高级特性（如部分预渲染的 CDN 分发细节、Fluid Compute 优化、边缘 Middleware 的极低延迟）在 Vercel 上体验最佳。迁移到其他平台时可能需要做功能取舍或架构调整。

十、 生态地图

Next.js 坐拥全行业最强大的生产级组件与工具链生态：

graph LR
  Next[Next.js 核心] --> Style[样式与UI]
  Next --> Db[数据库与ORM]
  Next --> Auth[身份认证]
  Next --> State[状态与获取]
  Next --> Dev[工程化与部署]
  Next --> AI[AI 与 LLM]
 
  Style --> Tailwind[Tailwind CSS]
  Style --> Radix[Radix Headless]
  Style --> Shadcn[shadcn/ui]
 
  Db --> Drizzle[Drizzle ORM]
  Db --> Prisma[Prisma ORM]
  Db --> Postgres[PostgreSQL / Neon]
 
  Auth --> AuthJS[Auth.js / NextAuth]
  Auth --> Clerk[Clerk 托管服务]
 
  State --> Zustand[Zustand]
  State --> SWR[SWR]
  State --> Query[React Query]
 
  Dev --> Biome[Biome / ESLint]
  Dev --> Turborepo[pnpm Monorepo]
  Dev --> Vercel[Vercel Platform]
 
  AI --> AISDK[Vercel AI SDK]
  AI --> OpenAI[OpenAI SDK]

十一、 生态集成

以下是 Next.js 全栈方案中，最为主流且经过生产级验证的最佳集成搭配方案：

十二、 开发与工程化

1. 严格模式与类型校验

Next.js 与 TypeScript 强绑定。在生产环境执行 pnpm build 时，框架会自动进行全方位的类型诊断和 Lint。

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "jsx": "preserve",
    "moduleResolution": "bundler"
  }
}

2. 现代工程 Linter 与格式化 (Biome)

在 2026 年，更推荐使用快 Webpack/ESLint 十倍以上的 Biome 作为代码风格化工具：

{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "semicolons": "asNeeded"
    }
  }
}

3. pnpm Monorepo 与 Turborepo 协作

对于中大型企业，使用 Monorepo 划分应用包和共享 UI 包。在 packages/ui/ 中定义共享原子组件，并在 apps/web/next.config.ts 中配置：

const nextConfig: NextConfig = {
  transpilePackages: ['@repo/ui']
}

4. next-intl 国际化配置示例

// src/i18n/config.ts
import { getRequestConfig } from 'next-intl/server'
 
export default getRequestConfig(async () => {
  const locale = 'zh-CN' // 根据请求头或 cookie 动态获取
 
  return {
    locale,
    messages: (await import(`./messages/${locale}.json`)).default
  }
})

// src/app/layout.tsx
import { NextIntlClientProvider } from 'next-intl'
import { getMessages } from 'next-intl/server'
 
export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const messages = await getMessages()
 
  return (
    <html lang="zh-CN">
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  )
}

十三、 性能与安全

1. 彻底消除服务端获取瀑布流 (Waterfall)

每一个 await 的顺序执行都会导致网络请求的串行。如果是独立的数据获取，绝对禁止串行等待：

• 错误做法 (顺序执行，双倍耗时)：

  const user = await fetchUser()        // 等待 200ms
  const config = await fetchConfig()    // 等待 200ms，总计耗时 400ms

• 正确做法 (并行获取，节省一半时间)：

  const [user, config] = await Promise.all([
    fetchUser(),
    fetchConfig()                       // 同时发出请求，耗时仅 200ms
  ])

• 页面组件细粒度拆分骨架屏 (战略性 Suspense 边界)：

  export default function Page() {
    return (
      <main>
        <Header /> {/* 静态或快数据组件，瞬间渲染 */}
        <Suspense fallback={<ProductSkeleton />}>
          <SlowProductDetail /> {/* 耗时组件，后台流式加载 */}
        </Suspense>
      </main>
    )
  }

2. 避免在 RSC 边界内重复序列化

数据在跨越 Server -> Client 边界传递时，会被转化为 JSON。对大数组对象进行精细的结构裁剪：

// 错误：传递完整 User 对象
<ClientUserList users={allUsers} />
 
// 正确：仅传递客户端需要的字段
const strippedUsers = allUsers.map(u => ({ id: u.id, name: u.name, avatar: u.avatar }))
<ClientUserList users={strippedUsers} />

3. 静态 I/O 提升至模块最外层 (Hoist to Module Level)

若读取运行期间永不改变的静态资源，绝对禁止在路由处理器内部进行同步读取：

// 错误：每次请求都读文件
export async function GET() {
  const template = readFileSync('./template.html') // 严重阻塞！
  return new Response(template)
}
 
// 正确：模块初始化时只读取一次
const templatePromise = fs.readFile('./template.html', 'utf-8')
 
export async function GET() {
  const template = await templatePromise // 零 I/O 开销
  return new Response(template)
}

4. Server Actions 安全授权与 Zod 防御

Server Actions 本质上是公开 HTTP 端点，绝对不能因为其写法像本地函数就忽略安全防御：

'use server'
 
import { verifySession } from '@/lib/auth'
import { z } from 'zod'
 
const DeletePostSchema = z.object({
  postId: z.string().uuid()
})
 
export async function deletePost(rawParams: unknown) {
  // 1. Zod 防御校验
  const { postId } = DeletePostSchema.parse(rawParams)
 
  // 2. 鉴权校验
  const session = await verifySession()
  if (!session || session.user.role !== 'admin') {
    throw new Error('Unauthorized action')
  }
 
  // 3. 执行核心业务逻辑
  await db.post.delete({ id: postId })
  return { success: true }
}

5. Middleware 安全与 CSRF 防护

• Middleware 运行在 Edge Runtime，无法直接访问 Node.js 原生模块或数据库连接池。需要鉴权时应通过 JWT 校验或调用外部认证服务，避免直接访问数据库。
• Server Actions 默认集成 CSRF 防护（通过 SameSite cookies 和 Origin 校验），但自定义 Route Handler 中处理 POST 请求时必须手动校验 Origin 与 CSRF Token。

6. React View Transitions 流畅导航

Next.js 16 配合 React 19 View Transitions API，可实现原生感动画。使用 transitionTypes 属性或 startTransition + addTransitionType 触发方向性导航：

// src/components/DirectionalTransition.tsx
import { ViewTransition } from 'react'
 
export function DirectionalTransition({ children }: { children: React.ReactNode }) {
  return (
    <ViewTransition
      enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
      exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
      default="none"
    >
      {children}
    </ViewTransition>
  )
}

// 页面组件中使用
export default function ProductPage() {
  return (
    <DirectionalTransition>
      <div>
        <ProductDetail />
      </div>
    </DirectionalTransition>
  )
}

/* global.css */
:root {
  --duration-exit: 150ms;
  --duration-enter: 210ms;
  --duration-move: 400ms;
}
 
@keyframes fade {
  from { opacity: 0; }
  to { opacity: 1; }
}
 
@keyframes slide-x {
  from { transform: translateX(var(--slide-offset, 0)); }
  to { transform: translateX(0); }
}
 
::view-transition-new(.slide-from-right) {
  --slide-offset: 60px;
  animation: var(--duration-enter) ease-out var(--duration-exit) both fade,
             var(--duration-move) ease-in-out both slide-x;
}
 
::view-transition-old(.slide-to-left) {
  --slide-offset: -60px;
  animation: var(--duration-exit) ease-in both fade reverse,
             var(--duration-move) ease-in-out both slide-x reverse;
}
 
@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(*),
  ::view-transition-new(*),
  ::view-transition-group(*) {
    animation-duration: 0s !important;
  }
}

十四、 技术对比

以下是 2026 年现代主流 Web 全栈元框架的全方位核心特性与架构能力对比：

十五、 最佳实践 (结合本项目工程规范)

1. 页面层仅作路由装配与数据边界： 在 src/app/ 下的页面文件 (如 page.tsx) 中，不要堆积复杂的 UI 代码。页面文件应仅负责获取数据、挂载 Layout、并扮演“数据装配工”的角色。真正的核心 UI 应解耦至 src/features/ 或 src/components/ 下。

2. API 后端业务逻辑禁止留在路由目录： 遵循 apps/api/src/modules/<feature>/ 的三层架构。app/api/ 或 src/app/api/ 下的 Route Handlers 只应负责 HTTP 入口、鉴权包装和响应序列化，业务编排、DB 访问、Prompt、mapper 等应放在 modules/<feature>/ 下。

3. 绝对避免桶文件 (Barrel Files) 导入： 在导入 lucide-react 或大型 UI 组件库时，避免直接从根路径导入。在 next.config.ts 中启用 optimizePackageImports：

   experimental: {
     optimizePackageImports: ['lucide-react', '@repo/ui']
   }

4. 将静态 I/O 读取提升至模块最外层 (Hoist to Module Level)： 读取运行期间永不改变的静态资源时，将 readFile Promise 提升到模块顶层，避免每次 HTTP 请求重复 I/O。

5. 统一使用 React View Transitions API 进行流畅视觉过渡： 使用 <ViewTransition> 组件包裹页面内容，结合 startTransition + addTransitionType 或 Next.js Link transitionTypes 触发方向性导航，并配套 CSS 动画配方与 prefers-reduced-motion 媒体查询。

6. 为公开页面同步维护 SEO 元数据： 新增或更新公开路由时，同步检查 sitemap.ts、robots.ts 和 llms.txt。登录后页面、编辑器页面设置 noindex，并确保 JSON-LD 与页面可见内容一致。

7. 测试策略与工程验证： 单元测试放在 apps/tests/ 或 tests/ 目录，不要把 .test.ts 放进 src/。UI 改动优先用 typecheck、build、浏览器验收与关键路径 E2E 验证。交付前必须运行 pnpm verify 或等价的验证命令。

8. Server Actions 安全三件套： 每个 Server Action 必须执行：① Zod 输入校验；② Session 鉴权与授权；③ 最小权限的数据库操作。绝不暴露未授权的数据库查询或管理操作。

9. Suspense 与错误边界分离关注点： 为慢数据组件添加 loading.tsx，为可能抛错的数据源添加 error.tsx，让页面具有优雅降级能力。避免在单个 page.tsx 中同时处理大量异步 await。

10. commit 前运行 pnpm verify： 提交信息遵循 Conventional Commits 中文规范：<type>(<scope>): <中文描述>。提交前运行 pnpm verify 确保类型、Lint 和测试均通过。

十六、 学习与社区资源

1. 官方核心资源

• Next.js 官方权威文档：https://nextjs.org/docs
• Next.js 互动学习课堂：https://nextjs.org/learn
• Next.js 官方博客 (追踪最新 PPR 和 v16 动态)：https://nextjs.org/blog
• Vercel 官方精品全栈模板库：https://vercel.com/templates/next.js

2. 社区高质量进阶教程

• Jack Herrington YouTube 频道：业内深度分析 React Server Components 与 Next.js 精准设计模式的最佳视频源。
• ByteGrad / Web Dev Simplified：专注于将晦涩的 Next.js 四层缓存、Middleware 路由拦截做通俗易懂拆解的专业教程。
• 《Real World Next.js》 — O'Reilly 生产级经典案例实践红宝书。
• 《The Next.js Handbook》 — Flavio Copes 极简、快速上手速查口袋书。