NNext.js 中文网 GitHub

构建交互式应用

了解如何使用 Server Functions、transition、乐观 UI 和 pending 反馈构建响应迅速的交互。

当一次用户交互需要服务端工作时,结果无法立即获得。网络请求需要的时间长短不定,可能成功也可能失败。在等待期间,客户端应提供反馈并响应这些状态。否则,用户只能看着过时的数据,不知道是否发生了什么。

本指南为一个名为 Taskboard 的任务管理应用添加响应式反馈。每一步处理不同类型的 pending 工作,从流式渲染缓慢的读取操作,到在服务端响应前确认变更操作。

小知识: 本指南中的模式还能改善 Core Web Vitals。使用 <Suspense> 进行流式渲染,可以在缓慢的读取操作完成时先绘制外壳,从而降低 FCP 和 LCP。乐观 UI 和 transition 通过保持点击帧的快速响应来降低 INP。预取下一个路由可让目标页面的 FCP、LCP 和 INP 近乎瞬时。这些模式有所帮助,但不能替代常规的 INP 优化工作:减少客户端 JavaScript 的交付量,并避免交互期间出现阻塞性的往返请求。

示例#

这些模式按顺序逐步构建:在加载边界后流式渲染缓慢的数据、添加即时的优先级切换、使用回调 prop 构建可复用的筛选器、在评论被确认前先显示它们、在拖放时于各列之间移动卡片、在创建对话框中管理表单生命周期,以及向父组件传递 pending 删除的信号。最后一步缓存可复用的读取操作,使导航保持瞬时。

配套的 Taskboard 演示(源代码)让你可以在实际运行中查看本指南中的每种模式。

该应用按功能组织。任务领域的一切内容(查询、Server Functions 和组件)都位于 features/task/ 下。共享的 UI 基础组件位于 components/ui/,而 app/ 中的页面负责组合功能组件。本指南全文中的文件路径都遵循这一结构。

起点是一个 Server Component 应用,它从数据库读取任务和评论,没有 <Suspense> 边界,也没有缓存。Client Components 调用 Server Functions 来变更这些数据。每次变更后,Server Function 都会调用 refresh(),使服务端使用新数据重新渲染:

features/task/task-actions.ts
'use server'

import { refresh } from 'next/cache'
import { PRIORITY_CYCLE } from '@/lib/data'
import { getTaskById, updateTaskPriority } from '@/lib/db'

export async function cyclePriority(taskId: string) {
  const task = await getTaskById(taskId)
  if (!task) return null
  const newPriority = PRIORITY_CYCLE[task.priority]
  await updateTaskPriority(taskId, newPriority)
  refresh()
  return newPriority
}

步骤 1:使用 Suspense 流式渲染缓慢的数据#

任务详情页会读取任务及其评论。当在页面组件顶部同时 await 这两项时,整个页面会阻塞,直到最慢的读取操作完成。

app/task/[id]/page.tsx
import { getTask } from '@/features/task/task-queries'
import { TaskDetail } from '@/features/task/components/task-detail'
import { CommentSection } from '@/features/task/components/comment-section'

export default async function TaskPage({ params }) {
  const { id } = await params
  const task = await getTask(id)

  return (
    <div>
      <TaskDetail task={task} />
      <CommentSection taskId={id} />
    </div>
  )
}

在这个版本中,在 getTask 完成之前不会渲染任何内容,而评论的读取只会在那之后才开始。

将读取操作拆分到不同的组件中,为每个组件传入一个 promise,并用 <Suspense> 将它们包裹起来。页面变为同步的,会立即返回外壳,服务端则在各部分数据就绪时逐一流式渲染:

app/task/[id]/page.tsx
import { Suspense } from 'react'
import {
  TaskDetail,
  TaskDetailSkeleton,
} from '@/features/task/components/task-detail'
import {
  CommentSection,
  CommentSectionSkeleton,
} from '@/features/task/components/comment-section'

export default function TaskPage({ params }) {
  return (
    <div>
      <Suspense fallback={<TaskDetailSkeleton />}>
        {params.then(({ id }) => (
          <>
            <TaskDetail id={id} />
            <Suspense fallback={<CommentSectionSkeleton />}>
              <CommentSection taskId={id} />
            </Suspense>
          </>
        ))}
      </Suspense>
    </div>
  )
}

每个区块组件各自 await 自己的数据:

features/task/components/task-detail.tsx
export async function TaskDetail({ id }) {
  const task = await getTask(id)
  return <TaskHeader task={task} />
}

在 JSX 中内联调用 params.then() 使页面保持同步。外层的 <Suspense> 覆盖了 params 的解析和任务详情的读取。一旦 TaskDetail 完成,React 就会显示任务头部和嵌套的 <Suspense> 边界,后者会在评论加载期间显示 CommentSectionSkeleton。

现在页面外壳会立即绘制,getTask 完成时任务头部会流式渲染进来,getComments 完成时评论区紧随其后。

有关流式渲染模式的更多信息,请参阅流式渲染指南。

步骤 2:即时响应切换操作#

每张任务卡片都有一个优先级指示器,点击时会在低、中、高之间循环切换。

该按钮渲染来自服务端的 priority prop。调用 Server Function 会启动变更操作,但不会改变当前渲染中的该 prop。

这里直接调用了 Server Function:

features/task/components/task-card.tsx
'use client'

import { cyclePriority } from '@/features/task/task-actions'

export function TaskCard({ id, priority }) {
  return (
    <button onClick={() => cyclePriority(id)} className={priorityDot[priority]}>
      {priority}
    </button>
  )
}

如果点击该圆点,Server Function 会运行,但按钮会继续渲染旧的 priority prop,直到下一次服务端渲染到达。

将直接调用替换为 useOptimistic 和 useTransition。useOptimistic 提供一个值来代替过时的 prop 进行渲染,useTransition 则将 Server Function 作为 transition 的一部分运行。只要该 transition 处于 pending 状态,乐观值就会生效:

features/task/components/task-card.tsx
'use client'

import { useOptimistic, useTransition } from 'react'
import { cyclePriority } from '@/features/task/task-actions'
import { PRIORITY_CYCLE } from '@/lib/data'

export function TaskCard({ id, priority }) {
  const [optimisticPriority, setOptimisticPriority] = useOptimistic(priority)
  const [, startTransition] = useTransition()

  function handlePriority() {
    startTransition(async () => {
      setOptimisticPriority(PRIORITY_CYCLE[optimisticPriority])
      await cyclePriority(id)
    })
  }

  return (
    <button
      onClick={handlePriority}
      className={priorityDot[optimisticPriority]}
    >
      {optimisticPriority}
    </button>
  )
}

setOptimisticPriority 调用会在当前帧用循环中的下一个值更新 UI。从 optimisticPriority 而非 prop 读取,意味着快速双击也能正确循环,而不会读取到过时的闭包值。

当 transition 结束且新数据到达时,乐观值会回退到新的服务端渲染 prop。如果 useTransition 内的 Server Function 抛出异常,错误会被转发到最近的错误边界,无需手动编写 try/catch。

现在颜色会在鼠标抬起的瞬间改变。再次点击会循环到下一个值,无需等待第一次变更完成。

步骤 3:带 pending 反馈的筛选#

看板带有标签筛选按钮(Design、Frontend、Backend)。点击某个按钮会更新查询参数以筛选任务列表。

选中的筛选条件来自 URL。调用 router.push() 会启动客户端导航,服务端会用新的 search params 重新渲染看板。在该导航完成之前,页面会继续渲染旧的 URL 状态。

这里直接调用了 router.push():

features/task/components/label-filter.tsx
'use client'

import { useRouter, useSearchParams } from 'next/navigation'

export function LabelFilter() {
  const router = useRouter()
  const searchParams = useSearchParams()

  function handleFilter(value: string | null) {
    const params = new URLSearchParams(searchParams.toString())
    if (value) params.set('label', value)
    else params.delete('label')
    router.push(`/?${params.toString()}`)
  }

  // ...使用 onClick={handleFilter} 渲染筛选按钮
}

在这个版本中,router.push() 会启动导航,但没有本地的 pending 状态。按钮继续渲染旧的 URL 值,看板也没有任何迹象表明新的服务端渲染正在加载。

将筛选器拆分为两个组件。LabelFilter 负责查询字符串的更新,并将导航回调传递给可复用的 ChipGroup,由后者处理所有 pending 反馈:

features/task/components/label-filter.tsx
'use client'

import { useRouter, useSearchParams } from 'next/navigation'
import { ChipGroup } from '@/components/ui/chip-group'

const labels = [
  { label: 'Design', value: 'design' },
  { label: 'Frontend', value: 'frontend' },
  { label: 'Backend', value: 'backend' },
]

export function LabelFilter() {
  const router = useRouter()
  const searchParams = useSearchParams()
  const current = searchParams.get('label') ?? null

  function filterAction(value: string | null) {
    const params = new URLSearchParams(searchParams.toString())
    if (value) {
      params.set('label', value)
    } else {
      params.delete('label')
    }
    router.push(`/?${params.toString()}`)
  }

  return (
    <ChipGroup items={labels} value={current} changeAction={filterAction} />
  )
}

LabelFilter 决定应用导航到哪里,自身不持有任何 pending 状态。

在内部处理 pending 反馈#

ChipGroup 接受一个 changeAction prop,并在自己的 startTransition 中调用它。它使用了两个 useOptimistic hook:一个用于选中的按钮,另一个用于 data-pending 属性,祖先组件可以基于该属性设置样式:

components/ui/chip-group.tsx
'use client'

import { startTransition, useOptimistic } from 'react'

export function ChipGroup({ items, value, changeAction }) {
  const [optimisticValue, setOptimisticValue] = useOptimistic(value)
  const [isPending, setIsPending] = useOptimistic(false)

  function handleClick(newValue) {
    startTransition(async () => {
      setOptimisticValue(newValue)
      setIsPending(true)
      await changeAction(newValue)
    })
  }

  return (
    <div className="flex gap-1.5" data-pending={isPending ? '' : undefined}>
      {items.map((item) => (
        <button
          key={item.value}
          onClick={() =>
            handleClick(item.value === optimisticValue ? null : item.value)
          }
          className={item.value === optimisticValue ? 'active' : ''}
        >
          {item.label}
        </button>
      ))}
    </div>
  )
}

使用者传入一个回调(changeAction),设计组件在 transition 中运行它。按照惯例,名为 action 或以 Action 结尾的 prop 表示这种行为。有关此模式,请参阅 React 文档中的从组件暴露 action prop。

ChipGroup 根元素上的 data-pending 属性让祖先组件无需任何协调即可通过 CSS 做出响应。首页的看板使用 group-has-data-pending:opacity-50 在 transition 运行期间变暗,而不是用骨架屏替换看板。由于 ChipGroup 渲染在 group 元素内部,该属性对任何祖先组件都可用于设置样式。

小知识: group-has-data-pending: 和 has-data-pending: 会编译为 CSS 的 :has() 选择器,每当 data-pending 切换时,浏览器都会对锚定子树重新求值。在这里开销很小,因为看板每次筛选只切换两次,而拖动(步骤 5)特意跳过了它。当宽泛的 :has() 锚点在拖动或滚动等高频交互中切换时,应改用客户端状态,因为对大型子树反复重新计算会累积开销。

"Frontend" 按钮现在会在当前帧高亮。看板在筛选数据加载期间变暗,随后更新为筛选后的任务。

步骤 4:添加带即时反馈的评论#

任务详情页有一个评论区。提交评论会在服务端写入新数据,但持久化列表由 Server Component 渲染,因此在下一次服务端渲染到达之前,它无法包含新评论。

这里的评论表单使用受控状态管理输入框,并直接调用 Server Function:

features/task/components/comment-form.tsx
'use client'

import { useState } from 'react'
import { addComment } from '@/features/task/task-actions'

export function CommentForm({ taskId }) {
  const [content, setContent] = useState('')

  async function handleSubmit() {
    if (!content.trim()) return
    await addComment(taskId, content)
    setContent('')
  }

  return (
    <div>
      <input
        value={content}
        onChange={(e) => setContent(e.target.value)}
        placeholder="Write a comment..."
      />
      <button onClick={handleSubmit}>Send</button>
    </div>
  )
}

在这个版本中,提交时 Server Function 会运行,但输入框保持有内容,列表在服务端响应前不会变化。

将评论列表拆分为两部分。一个 Server Component 渲染持久化的评论,一个 Client Component 仅用 useOptimistic([])(初始为空数组)跟踪 pending 评论。当 transition 完成且带有新数据的新渲染到达时,pending 列表重置为空,真正的评论出现在服务端渲染的列表中:

features/task/components/optimistic-comments.tsx
'use client'

import { useOptimistic, useRef } from 'react'
import { addComment } from '@/features/task/task-actions'
import { CommentCard } from './comment-card'

export function OptimisticComments({ taskId }) {
  const [pendingComments, setPendingComments] = useOptimistic([])
  const formRef = useRef(null)

  return (
    <>
      <form
        ref={formRef}
        action={async (formData) => {
          const content = formData.get('content')?.trim()
          if (!content) return
          formRef.current?.reset()

          const id = crypto.randomUUID()
          setPendingComments((current) => [
            {
              id,
              content,
              userName: 'You',
              createdAt: new Date().toISOString(),
            },
            ...current,
          ])

          await addComment(taskId, content)
        }}
      >
        <input name="content" placeholder="Write a comment..." required />
        <button type="submit">Send</button>
      </form>
      {pendingComments.map((comment) => (
        <CommentCard key={comment.id} comment={comment} pending />
      ))}
    </>
  )
}

提交时会发生三件事:

  1. formRef.current?.reset() 通过直接操作 DOM 清空输入框。在 transition 中,useState 的 setter 会延迟到 transition 完成后执行,但 useOptimistic 的 setter 和 formRef.reset() 这类直接 DOM 调用会在当前帧生效。
  2. setPendingComments 使用客户端生成的 UUID 将新评论添加到 pending 列表。
  3. 表单的 action 在 transition 中运行该处理函数。

Server Component 会在旁边渲染真实的列表:

features/task/components/comment-section.tsx
import { getComments } from '@/features/task/task-queries'
import { CommentCard } from './comment-card'
import { OptimisticComments } from './optimistic-comments'

async function CommentSection({ taskId }) {
  const comments = await getComments(taskId)

  return (
    <div>
      <OptimisticComments taskId={taskId} />
      {comments.map((comment) => (
        <CommentCard key={comment.id} comment={comment} />
      ))}
    </div>
  )
}

现在提交时输入框会清空,列表顶部会出现一张淡化的评论卡片。当服务端确认后,淡化的卡片消失,真正的评论出现在服务端渲染的列表中。

步骤 5:在各列之间移动卡片#

看板有三列:Todo、In Progress 和 Done。每一列根据服务端提供的 tasks prop 渲染任务。

放下卡片会启动一个写入新状态的 Server Function。在下次服务端渲染到达之前,tasks prop 不会变化,因此客户端需要一个临时任务列表来表示这次 pending 的移动。

这里在放下卡片时调用了 Server Function:

features/task/components/board.tsx
'use client'

import { use } from 'react'
import { updateStatus } from '@/features/task/task-actions'

export function Board({ tasksPromise }) {
  const tasks = use(tasksPromise)

  function handleDrop(targetStatus, taskId) {
    updateStatus(taskId, targetStatus)
  }

  // ...根据 tasks 渲染各列
}

该组件从父级 Server Component(见步骤 1 的 <Suspense> 边界)接收一个 promise,并用 use 解包。在这个版本中,从 "Todo" 拖到 "In Progress" 的卡片在服务端处理更新期间仍停留在旧列,等响应到达后才跳到新列。

添加带 reducer 的 useOptimistic,在当前帧重新映射卡片的状态。reducer 接收完整的任务列表和一个描述哪张卡片移动到何处的 action:

features/task/components/board.tsx
'use client'

import { startTransition, use, useOptimistic } from 'react'
import { toast } from 'sonner'
import { updateStatus } from '@/features/task/task-actions'

export function Board({ tasksPromise }) {
  const tasks = use(tasksPromise)
  const [optimisticTasks, moveTask] = useOptimistic(
    tasks,
    (currentTasks, action: { taskId: string; status: Status }) =>
      currentTasks.map((t) =>
        t.id === action.taskId ? { ...t, status: action.status } : t
      )
  )

  function handleDrop(targetStatus, taskId) {
    startTransition(async () => {
      moveTask({ taskId, status: targetStatus })
      const result = await updateStatus(taskId, targetStatus)
      if (!result.success) toast.error(result.error)
    })
  }

  return (
    <div className="grid grid-cols-3 gap-4">
      {columns.map((col) => (
        <Column
          key={col.status}
          tasks={optimisticTasks.filter((t) => t.status === col.status)}
          onDrop={(taskId) => handleDrop(col.status, taskId)}
        />
      ))}
    </div>
  )
}

reducer 遍历任务列表并更新被拖动卡片的状态,其余保持不变。如果在拖动过程中有后台刷新到达(例如来自轮询或其他用户的变更),React 会用更新后的基础数据重新运行 reducer,使乐观移动叠加在新数据之上。当任务不再存在时,Server Function 会返回错误结果,客户端用 toast 显示该错误。

这一步使用独立的 startTransition 而非 useTransition,因为该 hook 的 isPending 会触发步骤 3 中的看板变暗效果。乐观移动已经提供了视觉反馈,因此不需要 pending 指示器。如果 Server Function 返回预期的错误,卡片会回退。非预期错误会被转发到最近的错误边界。

现在从 "Todo" 拖到 "In Progress" 的卡片在松手的瞬间就会落到目标列。

步骤 6:管理表单生命周期#

看板有一个 "New Task" 按钮,用于打开创建对话框。表单 action 在服务端创建任务,然后刷新看板。

在该 action 处于 pending 状态时,对话框协调三部分客户端状态:提交按钮、字段值以及对话框是否打开。useActionState 负责处理这三者。

这里的表单手动管理提交状态,并在 onSubmit 处理函数中调用 Server Function:

features/task/components/create-task-modal.tsx
'use client'

import { useState } from 'react'
import { createTask } from '@/features/task/task-actions'

export function CreateTaskModal() {
  const [isOpen, setIsOpen] = useState(false)
  const [isSubmitting, setIsSubmitting] = useState(false)

  async function handleSubmit(e) {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)
    const title = formData.get('title')
    if (!title.trim()) return

    setIsSubmitting(true)
    await createTask({ title /* ... */ })
    setIsSubmitting(false)
    setIsOpen(false)
  }

  return (
    <Dialog open={isOpen} onOpenChange={setIsOpen}>
      <form onSubmit={handleSubmit}>
        <input name="title" placeholder="Task title..." required />
        <button type="submit" disabled={isSubmitting}>
          {isSubmitting ? 'Creating...' : 'Create Task'}
        </button>
      </form>
    </Dialog>
  )
}

在这个版本中,提交处理函数会运行,但由两个独立的 useState 调用管理 pending 状态。对话框会在看板显示新任务之前关闭,因为 setIsOpen(false) 在 transition 之外触发。表单字段在多次提交之间也会保留其值,除非你自己跟踪一个重置 key。

useActionState 处理这三方面:isPending 用于按钮,基于 key 的重置用于字段,以及包裹对话框的关闭操作:

features/task/components/create-task-modal.tsx
'use client'

import { useActionState, startTransition, useState } from 'react'
import { createTask } from '@/features/task/task-actions'

export function CreateTaskModal() {
  const [isOpen, setIsOpen] = useState(false)

  const [{ key }, formAction, isPending] = useActionState(
    async (prev, formData) => {
      const title = String(formData.get('title'))
      if (!title.trim()) return prev

      await createTask({
        title,
        description: String(formData.get('description')),
        status: 'todo',
        priority: 'medium',
      })

      startTransition(() => setIsOpen(false))
      return { key: prev.key + 1 }
    },
    { key: 0 }
  )

  return (
    <Dialog open={isOpen} onOpenChange={setIsOpen}>
      <form action={formAction}>
        <div key={key}>
          <input name="title" placeholder="Task title..." required />
          <input name="description" placeholder="Describe the task..." />
        </div>
        <button type="submit" disabled={isPending}>
          {isPending ? 'Creating...' : 'Create Task'}
        </button>
      </form>
    </Dialog>
  )
}

返回状态中的 key 控制表单重置。成功后 key 递增,从而重新挂载 <div key={key}> 并重置其中的每个输入框。

useActionState 将 action 作为 transition 运行,因此在 createTask 运行期间对话框保持打开,isPending 保持为 true。await 之后的状态更新不会自动成为该 transition 的一部分,因此将 setIsOpen(false) 包裹在 startTransition 中,可让关闭操作作为 transition 的一部分运行。

有了这层包裹,React 会将对话框的关闭与 createTask 内部 refresh() 触发的看板更新一起批处理,因此新任务会在对话框关闭的瞬间出现。没有它的话,对话框会先关闭,看板则晚一帧更新。

小知识: React 文档中以 React 不会将我在 await 之后的状态更新视为 transition 记录了这一限制。在修复之前,推荐将 await 之后的状态更新包裹在 startTransition 中作为变通方案。

同样,await 之后的这个窗口也适合放置 toast 等副作用:

tsx
await createTask({
  /* … */
})

startTransition(() => setIsOpen(false))
toast.success('Task created')

不影响渲染状态的副作用(如分析、toast 和焦点变更)应在 await 完成后运行。它们不需要 transition,因为不会更新 React 状态。

现在按钮文本会在提交时变为 "Creating..." 并变暗。当服务端响应后,字段清空、对话框关闭、新任务出现在看板上,并有 toast 确认该操作。

小知识: 配套应用在对话框中添加了状态、优先级、负责人和标签选择器。模式相同:隐藏输入框跟踪每个选择器的状态,key 在成功时将它们全部重置。

步骤 7:向父组件传递 pending 删除信号#

每张评论卡片都有一个删除按钮,可在服务端删除评论,评论在下一次渲染后从列表中消失。

在点击与该次渲染之间,卡片仍显示旧数据。列表本身无法显示 pending 的删除,因此信号必须来自按钮。

这一步复用了步骤 3 中的 data-pending CSS 钩子,但由 useOptimistic(false) 驱动,而非 useTransition 的 isPending。

这里直接调用了 Server Function:

features/task/components/delete-button.tsx
'use client'

import { Trash2 } from 'lucide-react'
import { deleteComment } from '@/features/task/task-actions'

export function DeleteButton({ commentId }) {
  return (
    <button
      onClick={() => deleteComment(commentId)}
      aria-label="Delete comment"
    >
      <Trash2 className="size-3" />
    </button>
  )
}

在这个版本中,评论在下一次服务端渲染之前保持完全可见。

将该 action 包裹在 <form> 中,用 useOptimistic(false) 跟踪 pending 状态,并通过 data-pending 属性暴露出来。将 action 作为 deleteAction prop 接收,以便父级评论卡片通过 CSS 做出响应:

features/task/components/delete-button.tsx
'use client'

import { useOptimistic } from 'react'
import { Trash2 } from 'lucide-react'

export function DeleteButton({
  deleteAction,
}: {
  deleteAction: () => void | Promise<void>
}) {
  const [isPending, setIsPending] = useOptimistic(false)

  return (
    <form
      action={async () => {
        setIsPending(true)
        await deleteAction()
      }}
    >
      <button
        type="submit"
        disabled={isPending}
        data-pending={isPending ? '' : undefined}
        aria-label="Delete comment"
      >
        <Trash2 className="size-3" />
      </button>
    </form>
  )
}

父级评论卡片使用 Tailwind 的 has-data-pending: 变体,在任意后代设置 data-pending 属性时让自身淡出。按钮是唯一知道删除何时处于 pending 状态的组件,因此将该状态暴露为 CSS 属性,可让任何祖先组件自行变暗,而无需提升状态或层层传递回调:

features/task/components/comment-card.tsx
<div className="rounded-lg px-3 transition-all has-data-pending:opacity-30">
  
  {deleteAction && <DeleteButton deleteAction={deleteAction} />}
</div>

父级 Server Component 将 Server Function 绑定到评论 ID,从而保持 DeleteButton 的可复用性:

features/task/components/comment-section.tsx
<CommentCard
  comment={comment}
  deleteAction={
    comment.userName === 'You'
      ? deleteComment.bind(null, comment.id)
      : undefined
  }
/>

现在卡片在点击被注册的瞬间淡出到 30% 不透明度。当服务端确认且下一次渲染到达时,卡片从列表中卸载。

步骤 8:让重复导航瞬时完成#

到目前为止,每种模式都只是让单次交互更流畅。跨导航时,相同的读取会重新执行,相同的 fallback 会再次绘制。对可复用的读取进行缓存,并用真实请求预取它们,可以弥补这一不足,而无需将数据模型搬进浏览器。

这一步使用 Next.js 16 引入的 Cache Components。步骤 1 至 7 在不使用它的情况下也能工作。如果你没有使用 Cache Components,请参阅不使用 Cache Components 的缓存。

在 next.config.ts 中启用它:

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

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

启用 Cache Components 会对所有路由应用预渲染验证,而不仅是本步骤涉及的路由。在 <Suspense> 之外读取 cookies()、headers() 或 searchParams 等请求数据的路由现在会阻止预渲染,需要按步骤 1 的方式处理。要在现有应用中启用它,请参阅迁移到 Cache Components。

缓存可复用的读取#

对每一次服务端读取,都要考虑它是否应跨请求复用,以及每次写入能否精确地使其失效。任务足够稳定,适合缓存,并且有清晰的按 id 划分的标签:

features/task/task-queries.ts
import { cacheLife, cacheTag } from 'next/cache'
import { getTaskById } from '@/lib/db'

export async function getTask(id: string) {
  'use cache'
  cacheLife('hours')
  cacheTag('tasks', `task-${id}`)

  return getTaskById(id)
}

按 id 划分的标签 task-${id} 让单个任务拥有自己的句柄。更宽泛的 tasks 标签涵盖列表。有关缓存范围('use cache: private'、'use cache: remote')、缓存生命周期和标签模式,请参阅缓存指南。

通过变更操作使缓存失效#

refresh() 会重新运行动态工作,但保留缓存条目。对于每次写入涉及的标签,请用 updateTag 替换它:

features/task/task-actions.ts
'use server'

import { updateTag } from 'next/cache'
import { updateTaskStatus } from '@/lib/db'

export async function updateStatus(taskId: string, newStatus: Status) {
  const updated = await updateTaskStatus(taskId, newStatus)
  if (!updated) {
    return { success: false as const, error: 'Task no longer exists' }
  }

  updateTag('tasks')
  updateTag(`task-${taskId}`)
  return { success: true as const, status: newStatus }
}

每个 Server Function 都遵循相同的模式:执行写入,然后为发生变化的缓存读取调用 updateTag。动态读取没有需要失效的标签,因此这些变更操作应使用 refresh()。

在本演示中,评论串保持动态,因为读者期望当前讨论能在打开的任务页面上立即更新。添加或删除评论会调用 refresh(),为当前路由重新运行动态评论读取,同时保留任务缓存。有关标签模式、基于时间的重新验证以及从 Route Handler 进行按需失效,请参阅重新验证指南。

用真实请求预取目标页面#

在 Partial Prefetching(Next.js 16.3 及更高版本)下,<Link> 会预取目标页面的 App Shell:即针对当前用户在多个链接之间共享的路由输出。该外壳不包含 URL data,因为 params 和 searchParams 是与具体链接相关的。通过 prefetch={true} 让链接选择逐链接预取,即可在点击前解析这些 URL data:

features/task/components/task-card.tsx
<Link href={`/task/${id}`} prefetch={true}>
  
</Link>

当目标页面包含用户接下来很可能需要、且与具体 URL 相关的工作时,逐链接预取最有价值。缓存的读取让预取输出在 Client Cache 中可复用且可按标签失效;动态读取仍可在点击前解析,但每次预取都可能执行真正的服务端工作。在配套应用中,任务卡片会在滚动进入视口时预取详情页,因此用户点击时页面已能瞬时绘制。

后续步骤#

本指南中的模式组合了少量基础能力:

场景使用
缓慢的数据应在不阻塞页面的情况下流式渲染<Suspense>
某个值应在异步工作运行期间更新useOptimistic
异步工作需要 pending 状态、错误处理或协调的 UI 更新useTransition
表单需要 pending、重置和结果状态useActionState
祖先组件应为别处发生的工作显示 pending 状态data-pending 属性,配合 CSS 设置样式
可复用的读取应跨请求保留,并在写入后保持新鲜'use cache' 配合 cacheTag,由 updateTag 或 revalidateTag 重新验证
交互式应用中页面间的导航应感觉瞬时<Link> 预取结合 Partial Prefetching,以及通过 prefetch={true} 对依赖 URL data 的内容使用逐链接预取

大多数模式会混合使用其中两种或更多。选择适合你所要解决的约束的基础能力即可。

相关指南:

  • 客户端数据获取:介绍直接在浏览器中发起请求、从 Server Component 提供初始数据以及客户端缓存的协调
  • 流式渲染:介绍加载边界和 <Suspense> 模式
  • 即时导航:介绍如何验证导航保持瞬时
  • 视图过渡:介绍为状态变化添加动画
  • 单页应用:提供一个使用共享 reducer 的 useOptimistic 示例,使客户端与服务端列表更新保持同步
Next.js 中文网