nextjs-navigation

Next.js 导航

关于 Next.js App Router 导航模式、预取行为和导航专属优化的专业指导。

Link 预取行为

App Router 的预取行为与之前的 Next.js 版本有显著差异：

App Router 预取属性

• prefetch={false} - 禁用所有预取，包括悬停时的预取。在之前的 Next.js 版本中，这种设置仍会在悬停时预取。
• prefetch={undefined} - 仅预取静态路由，不预取动态路由。
• prefetch={true} - 同时预取静态和动态路由。

示例：

// No prefetching at all
<Link href="/dashboard" prefetch={false}>Dashboard</Link>

// Prefetch static routes only (default behavior)
<Link href="/about" prefetch={undefined}>About</Link>

// Prefetch both static and dynamic routes
<Link href="/posts/[id]" prefetch={true}>Post</Link>

当用户不太可能进行导航，或目标页面占用资源较多时，选择 prefetch={false}。对经常访问的动态路由使用 prefetch={true}，以提升用户感知到的性能。

Suspense 边界与搜索参数

仅搜索参数发生变化的同页导航不会重新触发 Suspense 边界。这意味着使用查询参数进行筛选或分页时，不会显示加载状态。

强制重新触发 Suspense

为 Suspense 边界添加一个包含变化的搜索参数的唯一 key 属性：

import { Suspense } from 'react';

export default function Page({ searchParams }: { searchParams: { filter?: string } }) {
  return (
    <Suspense key={searchParams.filter} fallback={<Loading />}>
      <DataTable filter={searchParams.filter} />
    </Suspense>
  );
}

key 的变化会强制 React 卸载并重新挂载 Suspense 边界，从而在获取数据期间显示后备内容。对于筛选、分页或任何会触发数据获取的搜索参数，都可以使用这种模式。

类型安全

PageProps 辅助类型

使用 PageProps 辅助类型，为 App Router 中页面组件的属性正确声明类型：

import { PageProps } from 'next';

export default function Page({ params, searchParams }: PageProps) {
  // params and searchParams are properly typed
}

这样无需手动定义类型，也能确保路由参数和搜索参数的类型安全。

保留客户端状态

在 next.config.js 中启用 cacheComponents 标志后，Next.js 会使用 React 的 <Activity> 组件，在客户端导航期间保留组件状态。

启用此实验性功能：

// next.config.js
module.exports = {
  experimental: {
    cacheComponents: true,
  },
};

导航离开某个路由并返回时，组件状态（表单输入、滚动位置和本地状态）会保留。这能改善多步骤流程的用户体验，也适用于用户返回未完成的表单时。