nextjs-developer

Next.js 开发者技能

概述

此技能全面涵盖使用 App Router（Next.js 15+）构建可用于生产环境的 Next.js 应用。内容包括 Server Components、React 19 支持、数据获取模式、路由、API 路由、缓存和性能优化。

核心能力

App Router 架构

• Server Components：默认渲染模式，可实现最佳性能
• Client Components：使用 "use client" 指令的交互式组件
• 布局：在不同路由间共享 UI 并保留状态
• 模板：导航时创建新实例（不保留状态）
• 加载 UI：通过 loading.tsx 文件实现流式加载
• 错误处理：通过 error.tsx 实现细粒度错误边界

数据获取

• 服务端数据获取：在 Server Components 中直接访问数据库/API
• 缓存策略：默认动态渲染、显式缓存和增量再生
• 重新验证：基于时间和按需使缓存失效
• 并行获取：优化数据加载模式

路由系统

• 基于文件的路由：根据文件结构自动生成路由
• 动态路由：[param] 和全捕获 [...slug] 模式
• 路由组：使用 (folder) 组织路由，但不影响 URL
• 并行路由：使用 @slot 同时渲染多个路由
• 拦截路由：使用 (.)、(..)、(...) 实现模态框模式

Server Actions

• 表单处理：通过 action 属性实现渐进增强
• 数据变更：在服务端修改数据
• 重新验证：数据变更后自动更新缓存
• 乐观更新：立即反馈 UI 的模式

实现模式

项目结构

app/
├── layout.tsx          # Root layout
├── page.tsx            # Home page
├── globals.css         # Global styles
├── (auth)/             # Route group
│   ├── login/page.tsx
│   └── register/page.tsx
├── dashboard/
│   ├── layout.tsx      # Dashboard layout
│   ├── page.tsx        # Dashboard home
│   ├── loading.tsx     # Loading UI
│   ├── error.tsx       # Error boundary
│   └── [id]/page.tsx   # Dynamic route
├── api/
│   └── [route]/route.ts # API routes
└── components/         # Shared components

组件模式

Server Component（默认）

// app/posts/page.tsx
async function PostsPage() {
  const posts = await db.posts.findMany()

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

export default PostsPage

Client Component

// app/components/counter.tsx
"use client"

import { useState } from "react"

export function Counter() {
  const [count, setCount] = useState(0)

  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  )
}

数据获取模式

动态渲染（默认）

// In Next.js 15+, fetch is uncached by default (implicit cache: 'no-store')
async function Page() {
  const data = await fetch('https://api.example.com/data')
  return <div>{data}</div>
}

静态生成（选择启用）

// Explicitly opt into caching
async function Page() {
  const data = await fetch('https://api.example.com/data', {
    cache: 'force-cache',
  })
  return <div>{data}</div>
}

基于时间的重新验证

async function Page() {
  const data = await fetch('https://api.example.com/data', {
    next: { revalidate: 3600 }, // Revalidate every hour
  })
  return <div>{data}</div>
}

注意：在 Next.js 15 中，客户端路由缓存默认也不缓存，取代了旧版的 30s/5m 默认设置。

Server Actions

// app/actions.ts
"use server"

import { revalidatePath } from "next/cache"

export async function createPost(formData: FormData) {
  const title = formData.get("title") as string

  await db.posts.create({ data: { title } })

  revalidatePath("/posts")
}

// app/posts/new/page.tsx
import { createPost } from "@/app/actions"

export default function NewPost() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <button type="submit">Create</button>
    </form>
  )
}

部分预渲染（PPR）

• PPR 在单个 HTTP 请求中结合静态外壳与动态流式传输。
• PPR 在 Next.js 15+ 中已可用于生产环境，在 Next.js 14 中则处于实验阶段。
• 在 next.config.js 中设置 experimental.ppr: 'incremental' 以逐步采用，或者在需要完整 PPR 时使用 ppr: true。
• 使用 Suspense 边界在静态外壳中定义动态区域。
• 按路由逐步采用 PPR，逐渐扩大覆盖范围，无需重写整个应用。

// app/page.tsx — static shell with dynamic hole
export const experimental_ppr = true

export default function Page() {
  return (
    <main>
      <StaticHeader />
      <Suspense fallback={<ProductSkeleton />}>
        <DynamicProductList />
      </Suspense>
    </main>
  )
}

Turbopack

• Turbopack 在 Next.js 15 中适用于 next dev，并在 Next.js 15.3+ 中适用于 next build，且已稳定。
• 生产构建路径通过了 8,298 个测试套件用例。
• 使用 next dev --turbopack 和 next build --turbopack 启用。
• 与 Webpack 相比，它的开发服务器启动速度最高可快 10 倍。
• 某些 Webpack loader 和插件可能仍需迁移。

next dev --turbopack
next build --turbopack

React 19 功能

• React 19 是 Next.js 15+ App Router 项目的默认运行时。
• 使用 use() 在渲染期间使用 Promise 和上下文。
• Server Actions 已稳定，不再处于实验阶段。
• 使用 useFormStatus() 获取表单状态，无需逐层传递 props。
• 使用 useOptimistic() 实现乐观 UI 更新。

import { use } from "react"
import { useFormStatus } from "react-dom"
import { useOptimistic } from "react"

function ProductName({ productPromise }: { productPromise: Promise<{ name: string }> }) {
  const product = use(productPromise)
  return <h1>{product.name}</h1>
}

after() 响应后任务

• Next.js 15 引入了用于响应后任务的 after()。
• 使用它在发送响应后执行日志记录、分析等非关键任务。
• 从 next/server 导入。

import { after } from 'next/server'

after(() => {
  logAnalytics()
})

导航钩子（Next.js 15.4）

• useLinkStatus() 可用于显示内联链接加载指示器。
• onNavigate 可用于跟踪或阻止客户端导航。
• useLinkStatus() 是来自 next/link 的客户端钩子，返回 { pending }。
• onNavigate 是仅适用于 SPA 导航的 Link 属性。

'use client'

import Link, { useLinkStatus } from 'next/link'

function LinkHint() {
  const { pending } = useLinkStatus()
  return <span aria-hidden>{pending ? 'Loading…' : null}</span>
}

export function Nav() {
  return (
    <nav>
      <Link href="/dashboard" prefetch={false} onNavigate={() => trackNavigation('/dashboard')}>
        Dashboard <LinkHint />
      </Link>
    </nav>
  )
}

next.config.js 模式

• 仅在需要时保留实验性标志；Next.js 15+ 中的多项功能已转为稳定版。
• 使用 experimental.ppr: 'incremental'，逐个路由采用 PPR。
• 只有在需要为整个应用启用 PPR 时，才使用 ppr: true。
• Turbopack 通过 CLI 标志启用，而不是通过 next.config.js 开关。

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    ppr: 'incremental',
  },
  // For full PPR:
  // ppr: true,
}

export default nextConfig

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build --turbopack"
  }
}

最佳实践

性能

• 默认使用 Server Components
• 除非明确需要缓存，否则优先采用动态渲染
• 使用 PPR 实现快速静态外壳，并在其中嵌入动态内容
• 使用 next/image 优化图像
• 使用 next/font 优化字体
• 通过 Suspense 边界实现流式传输

安全

• 在 Server Actions 中验证所有输入
• 使用环境变量存储密钥
• 实现恰当的身份验证模式
• 清理用户生成的内容

代码组织

• 尽可能将组件与路由放在一起
• 使用路由组进行逻辑组织
• 实现恰当的错误边界
• 创建可复用的布局模式

脚本

此技能在 scripts/ 文件夹中包含可执行脚本：

开发

• dev-server.sh：启动支持热重载的开发服务器

  ./scripts/dev-server.sh [--port PORT] [--turbo]
  

• build-production.sh：创建经过优化的生产构建

  ./scripts/build-production.sh [--analyze]
  

• analyze-bundle.sh：分析打包体积和依赖项

  ./scripts/analyze-bundle.sh
  

代码生成

• create-page.sh：生成新页面，可选添加布局、加载和错误文件

  ./scripts/create-page.sh <page-path> [--layout] [--loading] [--error]
  

• create-api-route.sh：生成 API 路由处理程序

  ./scripts/create-api-route.sh <route-name> [--dynamic]
  

• create-component.sh：生成 React 组件，可选添加测试

  ./scripts/create-component.sh <name> [--client] [--test] [--dir DIR]
  

测试

• setup-testing.sh：设置 Jest 和 React Testing Library

  ./scripts/setup-testing.sh [--playwright]
  

• run-tests.sh：使用各种选项运行测试

  ./scripts/run-tests.sh [--watch] [--coverage] [--file FILE]
  

模板

此技能在 templates/ 文件夹中包含可用于生产环境的模板：

页面

• page-server.tsx：包含异步数据获取、元数据和 Suspense 流式传输的 Server Component 页面
• page-client.tsx：包含状态管理、钩子和交互功能的 Client Component 页面
• page-dynamic.tsx：包含 params、generateStaticParams 和 generateMetadata 的动态路由页面

组件

• component-server.tsx：包含数据获取和组合模式的 Server Component
• component-client.tsx：包含钩子、事件处理程序和 localStorage 的 Client Component

API 与后端

• api-route.ts：完整的 API 路由处理程序，包含 CRUD、验证（Zod）、身份验证和 CORS
• server-action.ts：包含表单处理、验证和重新验证的 Server Actions
• middleware.ts：包含身份验证、速率限制、i18n 和安全标头的中间件

基础设施

• layout.tsx：包含导航、页脚、元数据和字体的根布局／嵌套布局
• page.test.tsx：针对页面、组件、API 路由和 Server Actions 的测试模式

资源

此技能在 resources/ 文件夹中包含详细的参考指南：

• app-router-patterns.md：全面的 App Router 模式和示例
• data-fetching.md：数据获取策略和缓存
• server-components.md：Server Components 与 Client Components 指南
• routing-reference.md：完整的路由系统参考
• performance-optimization.md：性能最佳实践
• api-routes.md：API 路由处理程序和模式
• testing-patterns.md：Next.js 应用的测试策略

---

专长：Next.js App Router 开发 版本：2.0 最后更新：2026 年 5 月