链接

<Link> 是一个 React 组件，它扩展了 HTML <a> 元素，提供预取和路由之间的客户端导航功能。它是 Next.js 中在路由之间导航的主要方式。

基本用法：

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return <Link href="/dashboard">Dashboard</Link>
}

参考

以下属性可以传递给 <Link> 组件：

属性	示例	类型	必需
`href`	`href="/dashboard"`	String 或 Object	是
`as`	`as="/post/abc"`	String 或 Object	-
`replace`	`replace={false}`	Boolean	-
`scroll`	`scroll={false}`	Boolean	-
`prefetch`	`prefetch={false}`	Boolean	-
`shallow`	`shallow={false}`	Boolean	-
`locale`	`locale="fr"`	String 或 Boolean	-
`onNavigate`	`onNavigate={(e) => {}}`	Function	-

值得注意的是：<a> 标签的属性，如 className 或 target="_blank"，可以作为属性添加到 <Link> 中，并将传递给底层的 <a> 元素。

`href`（必需）

要导航到的路径或 URL。

pages/index.tsx

TypeScript

import Link from 'next/link'
 
// 导航到 /about?name=test
export default function Home() {
  return (
    <Link
      href={{
        pathname: '/about',
        query: { name: 'test' },
      }}
    >
      About
    </Link>
  )
}

`replace`

默认值为 false。 当为 true 时，next/link 将替换当前的历史状态，而不是向浏览器的历史记录栈中添加新的 URL。

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </Link>
  )
}

`scroll`

默认值为 true。 Next.js 中 <Link> 的默认滚动行为是保持滚动位置，类似于浏览器处理后退和前进导航的方式。当你导航到新的 Page 时，只要该 Page 在视口中可见，滚动位置就会保持不变。但是，如果 Page 在视口中不可见，Next.js 将滚动到第一个 Page 元素的顶部。

当 scroll = {false} 时，Next.js 不会尝试滚动到第一个 Page 元素。

值得注意的是：Next.js 在管理滚动行为之前会检查 scroll: false。如果启用了滚动，它会识别用于导航的相关 DOM 节点并检查每个顶层元素。所有不可滚动的元素和那些没有渲染 HTML 的元素都会被跳过，这包括粘性或固定定位的元素，以及不可见的元素，如那些用 getBoundingClientRect 计算的元素。Next.js 然后继续遍历兄弟元素，直到识别出一个在视口中可见的可滚动元素。

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/dashboard" scroll={false}>
      Dashboard
    </Link>
  )
}

`prefetch`

当 <Link /> 组件进入用户的视口（最初或通过滚动）时，会发生预取。Next.js 会在后台预取并加载链接的路由（由 href 表示）和数据，以提高客户端导航的性能。预取仅在生产环境中启用。

可以将以下值传递给 prefetch 属性：

true（默认）：将预取完整路由及其数据。
false：进入视口时不会进行预取，但会在悬停时进行预取。如果你想完全移除悬停时的预取，请考虑使用 <a> 标签或逐步采用 App Router，它也支持禁用悬停时的预取。

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/dashboard" prefetch={false}>
      Dashboard
    </Link>
  )
}

`shallow`

更新当前页面的路径而不重新运行 getStaticProps、getServerSideProps 或 getInitialProps。默认值为 false。

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/dashboard" shallow={false}>
      Dashboard
    </Link>
  )
}

`locale`

活动语言环境会自动添加前缀。locale 允许提供不同的语言环境。当为 false 时，href 必须包含语言环境，因为默认行为被禁用。

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <>
      {/* 默认行为：添加语言环境前缀 */}
      <Link href="/dashboard">Dashboard（带语言环境）</Link>
 
      {/* 禁用语言环境前缀 */}
      <Link href="/dashboard" locale={false}>
        Dashboard（不带语言环境）
      </Link>
 
      {/* 指定不同的语言环境 */}
      <Link href="/dashboard" locale="fr">
        Dashboard（法语）
      </Link>
    </>
  )
}

`as`

将在浏览器 URL 栏中显示的路径的可选装饰器。在 Next.js 9.5.3 之前，这用于动态路由，请查看我们的以前的文档以了解它是如何工作的。

当此路径与 href 中提供的路径不同时，将使用以前的 href/as 行为，如以前的文档中所示。

`onNavigate`

在客户端导航期间调用的事件处理程序。该处理程序接收一个包含 preventDefault() 方法的事件对象，允许你在需要时取消导航。

app/page.tsx

TypeScript

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // 仅在 SPA 导航期间执行
        console.log('正在导航...')
 
        // 可选择阻止导航
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

值得注意的是：虽然 onClick 和 onNavigate 可能看起来相似，但它们的用途不同。onClick 对所有点击事件执行，而 onNavigate 仅在客户端导航期间运行。一些关键区别：

当使用修饰键（Ctrl/Cmd + 点击）时，onClick 会执行，但 onNavigate 不会，因为 Next.js 会阻止在新标签页中的默认导航。

外部 URL 不会触发 onNavigate，因为它仅用于客户端和同源导航。

带有 download 属性的链接将使用 onClick 工作，但不会使用 onNavigate，因为浏览器会将链接的 URL 视为下载。

示例

以下示例演示了如何在不同场景中使用 <Link> 组件。

链接到动态路由段

对于动态路由段，使用模板字面量创建链接路径会很方便。

例如，你可以生成指向动态路由 pages/blog/[slug].js 的链接列表

pages/blog/index.tsx

TypeScript

import Link from 'next/link'
 
function Posts({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

滚动到 `id`

如果你想在导航时滚动到特定的 id，你可以在 URL 后附加一个 # 哈希链接，或者只需将哈希链接传递给 href 属性。这是可行的，因为 <Link> 会渲染为 <a> 元素。

<Link href="/dashboard#settings">Settings</Link>
 
// 输出
<a href="/dashboard#settings">Settings</a>

传递 URL 对象

Link 也可以接收 URL 对象，它会自动格式化以创建 URL 字符串：

pages/index.ts

TypeScript

import Link from 'next/link'
 
function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          About us
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          Blog Post
        </Link>
      </li>
    </ul>
  )
}
 
export default Home

上面的示例有一个链接指向：

预定义路由：/about?name=test
动态路由：/blog/my-post

你可以使用 Node.js URL 模块文档中定义的每个属性。

替换 URL 而不是推送

Link 组件的默认行为是将新 URL push 到 history 栈中。你可以使用 replace 属性来防止添加新条目，如下面的示例所示：

pages/index.js

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/about" replace>
      About us
    </Link>
  )
}

禁用滚动到页面顶部

Link 的默认行为是滚动到页面顶部。当定义了哈希时，它会滚动到特定的 id，就像普通的 <a> 标签一样。要防止滚动到顶部/哈希，可以将 scroll={false} 添加到 Link：

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/#hashid" scroll={false}>
      禁用滚动到顶部
    </Link>
  )
}

在 Proxy 中预取链接

通常使用 Proxy 进行身份验证或其他涉及将用户重写到不同页面的目的。为了让 <Link /> 组件通过 Proxy 正确预取带有重写的链接，你需要告诉 Next.js 要显示的 URL 和要预取的 URL。这是必需的，以避免不必要地获取代理以了解要预取的正确路由。

例如，如果你想提供一个具有已认证和访客视图的 /dashboard 路由，你可以在 Proxy 中添加以下内容以将用户重定向到正确的页面：

proxy.ts

TypeScript

import { NextResponse } from 'next/server'
 
export function proxy(request: Request) {
  const nextUrl = request.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (request.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', request.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', request.url))
    }
  }
}

在这种情况下，你需要在 <Link /> 组件中使用以下代码：

pages/index.tsx

TypeScript

'use client'
 
import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // 你的认证钩子
 
export default function Home() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

值得注意的是：如果你使用动态路由，你需要调整 as 和 href 属性。例如，如果你有一个动态路由如 /dashboard/authed/[user]，你想通过代理以不同方式呈现，你会这样写：<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>。

版本历史

版本	变更
`v15.4.0`	引入将 `auto` 作为默认 `prefetch` 行为的别名。
`v15.3.0`	引入 `onNavigate` API
`v13.0.0`	不再需要子 `<a>` 标签。提供了一个 codemod 来自动更新你的代码库。
`v10.0.0`	指向动态路由的 `href` 属性会自动解析，不再需要 `as` 属性。
`v8.0.0`	引入改进的预取性能。
`v1.0.0`	引入 `next/link`。