logoNext.js 简体中文
文档博客学习
简介/API 参考文档/组件/Link

Link

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

基本用法：

import Link from 'next/link'

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

export default function Home() {
  return <Link href="/dashboard">仪表盘</Link>
}

参考

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

属性示例类型必填
hrefhref="/dashboard"字符串或对象是
replacereplace={false}布尔值-
scrollscroll={false}布尔值-
prefetchprefetch={false}布尔值-
legacyBehaviorlegacyBehavior={true}布尔值-
passHrefpassHref={true}布尔值-
shallowshallow={false}布尔值-
localelocale="fr"字符串或布尔值-
onNavigateonNavigate={(e) => {}}函数-

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

href (必填)

要导航到的路径或 URL。

import Link from 'next/link'

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

// 导航到 /about?name=test
export default function Home() {
  return (
    <Link
      href={{
        pathname: '/about',
        query: { name: 'test' },
      }}
    >
      关于
    </Link>
  )
}

replace

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

import Link from 'next/link'

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

export default function Home() {
  return (
    <Link href="/dashboard" replace>
      仪表盘
    </Link>
  )
}

scroll

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

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

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

import Link from 'next/link'

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

export default function Home() {
  return (
    <Link href="/dashboard" scroll={false}>
      仪表盘
    </Link>
  )
}

prefetch

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

可以传递给 prefetch 属性的值：

  • true（默认）：将预加载完整路由及其数据。
  • false：进入视口时不会发生预加载，但在悬停时会预加载。如果您想完全移除悬停时的预加载，请考虑使用 <a> 标签或 逐步采用 应用路由，它也允许禁用悬停时的预加载。
import Link from 'next/link'

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

export default function Home() {
  return (
    <Link href="/dashboard" prefetch={false}>
      仪表盘
    </Link>
  )
}

legacyBehavior

警告：legacyBehavior 属性将在 Next.js v16 中移除。要采用新的 <Link> 行为，请移除作为 <Link> 子元素使用的任何 <a> 标签。提供了 codemod 帮助您自动升级代码库。

自版本 13 起，<a> 元素不再是 <Link> 组件的必需子元素。如果出于兼容性原因仍需要旧行为，可以添加 legacyBehavior 属性。

须知：当 legacyBehavior 未设置为 true 时，所有 anchor 标签属性都可以传递给 next/link，例如 className、onClick 等。

passHref

强制 Link 将 href 属性传递给其子元素。默认为 false。有关更多信息，请参阅 传递函数组件 示例。

shallow

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

import Link from 'next/link'

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

export default function Home() {
  return (
    <Link href="/dashboard" shallow={false}>
      仪表盘
    </Link>
  )
}

locale

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

import Link from 'next/link'

export default function Home() {
  return (
    <>
      {/* 默认行为：添加区域设置前缀 */}
      <Link href="/dashboard">仪表盘（带区域设置）</Link>

      {/* 禁用区域设置前缀 */}
      <Link href="/dashboard" locale={false}>
        仪表盘（不带区域设置）
      </Link>

      {/* 指定不同的区域设置 */}
      <Link href="/dashboard" locale="fr">
        仪表盘（法语）
      </Link>
    </>
  )
}
import Link from 'next/link'

export default function Home() {
  return (
    <>
      {/* 默认行为：添加区域设置前缀 */}
      <Link href="/dashboard">仪表盘（带区域设置）</Link>

      {/* 禁用区域设置前缀 */}
      <Link href="/dashboard" locale={false}>
        仪表盘（不带区域设置）
      </Link>

      {/* 指定不同的区域设置 */}
      <Link href="/dashboard" locale="fr">
        仪表盘（法语）
      </Link>
    </>
  )
}

onNavigate

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

import Link from 'next/link'

export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // 仅在 SPA 导航期间执行
        console.log('正在导航...')

        // 可选阻止导航
        // e.preventDefault()
      }}
    >
      仪表盘
    </Link>
  )
}
import Link from 'next/link'

export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // 仅在 SPA 导航期间执行
        console.log('正在导航...')

        // 可选阻止导航
        // e.preventDefault()
      }}
    >
      仪表盘
    </Link>
  )
}

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

  • 当使用修饰键（Ctrl/Cmd + 点击）时，onClick 会执行但 onNavigate 不会，因为 Next.js 阻止了新标签页的默认导航。
  • 外部 URL 不会触发 onNavigate，因为它仅用于客户端和同源导航。
  • 带有 download 属性的链接将与 onClick 一起工作，但不与 onNavigate 一起工作，因为浏览器会将链接 URL 视为下载。

示例

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

链接至动态路由段

对于 动态路由段 (dynamic route segments)，使用模板字面量创建链接路径会非常方便。

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

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>
  )
}
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>
  )
}

export default Posts

当子元素是包裹 <a> 标签的自定义组件时

如果 Link 的子元素是包裹 <a> 标签的自定义组件，你必须为 Link 添加 passHref 属性。这在使用了类似 styled-components 的库时是必需的。否则，<a> 标签将没有 href 属性，这会影响网站的可访问性并可能损害 SEO。如果你使用 ESLint，内置规则 next/link-passhref 会确保正确使用 passHref。

import Link from 'next/link'
import styled from 'styled-components'

// 创建一个包裹 <a> 标签的自定义组件
const RedLink = styled.a`
  color: red;
`

function NavLink({ href, name }) {
  return (
    <Link href={href} passHref legacyBehavior>
      <RedLink>{name}</RedLink>
    </Link>
  )
}

export default NavLink
import Link from 'next/link'
import styled from 'styled-components'

// 创建一个包裹 <a> 标签的自定义组件
const RedLink = styled.a`
  color: red;
`

function NavLink({ href, name }) {
  return (
    <Link href={href} passHref legacyBehavior>
      <RedLink>{name}</RedLink>
    </Link>
  )
}

export default NavLink
  • 如果你使用 emotion 的 JSX pragma 功能 (@jsx jsx)，即使直接使用 <a> 标签也必须添加 passHref。
  • 组件应支持 onClick 属性以正确触发导航。

嵌套函数式组件

如果 Link 的子元素是函数式组件，除了使用 passHref 和 legacyBehavior 外，还必须用 React.forwardRef 包裹组件：

import Link from 'next/link'
import React from 'react'

// 为 MyButton 定义 props 类型
interface MyButtonProps {
  onClick?: React.MouseEventHandler<HTMLAnchorElement>
  href?: string
}

// 使用 React.ForwardRefRenderFunction 正确类型化转发引用
const MyButton: React.ForwardRefRenderFunction<
  HTMLAnchorElement,
  MyButtonProps
> = ({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      点击我
    </a>
  )
}

// 使用 React.forwardRef 包裹组件
const ForwardedMyButton = React.forwardRef(MyButton)

export default function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}
import Link from 'next/link'
import React from 'react'

// `onClick`、`href` 和 `ref` 需要传递给 DOM 元素
// 以确保正确处理
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      点击我
    </a>
  )
})

// 为组件添加显示名称（便于调试）
MyButton.displayName = 'MyButton'

export default function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <MyButton />
    </Link>
  )
}

传递 URL 对象

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

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          关于我们
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          博客文章
        </Link>
      </li>
    </ul>
  )
}

export default Home
import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          关于我们
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          博客文章
        </Link>
      </li>
    </ul>
  )
}

export default Home

上面的例子包含以下链接：

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

替换 URL 而非压入

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

import Link from 'next/link'

export default function Home() {
  return (
    <Link href="/about" replace>
      关于我们
    </Link>
  )
}
import Link from 'next/link'

export default function Home() {
  return (
    <Link href="/about" replace>
      关于我们
    </Link>
  )
}

禁用滚动至页面顶部

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

import Link from 'next/link'

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

export default function Home() {
  return (
    <Link href="/#hashid" scroll={false}>
      禁用滚动至顶部
    </Link>
  )
}

在中间件中预取链接

通常我们会使用中间件 (Middleware) 来处理认证或其他需要重写用户页面的场景。为了让 <Link /> 组件能正确预取通过中间件重写的链接，你需要同时告知 Next.js 要显示的 URL 和需要预取的 URL。这样可以避免不必要的中间件请求来获取正确的预取路由。

例如，如果你想提供一个同时包含认证用户和访客视图的 /dashboard 路由，可以在中间件中添加以下代码来重定向用户到正确的页面：

import { NextResponse } from 'next/server'

export function middleware(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))
    }
  }
}
import { NextResponse } from 'next/server'

export function middleware(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 /> 组件中使用以下代码：

'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>
  )
}
'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>
  )
}

须知：如果使用动态路由 (Dynamic Routes)，你需要调整 as 和 href 属性。例如，如果你有一个动态路由 /dashboard/authed/[user] 想通过中间件展示不同内容，可以这样写：<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>。

阻止导航

你可以使用 onNavigate 属性在满足特定条件时阻止导航，例如表单有未保存的更改。当需要在应用中跨多个组件阻止导航时（比如在表单编辑期间阻止任何链接的导航），React Context 提供了一种清晰的方式来共享这个阻止状态。首先，创建一个上下文来跟踪导航阻止状态：

'use client'

import { createContext, useState, useContext } from 'react'

interface NavigationBlockerContextType {
  isBlocked: boolean
  setIsBlocked: (isBlocked: boolean) => void
}

export const NavigationBlockerContext =
  createContext<NavigationBlockerContextType>({
    isBlocked: false,
    setIsBlocked: () => {},
  })

export function NavigationBlockerProvider({
  children,
}: {
  children: React.ReactNode
}) {
  const [isBlocked, setIsBlocked] = useState(false)

  return (
    <NavigationBlockerContext.Provider value={{ isBlocked, setIsBlocked }}>
      {children}
    </NavigationBlockerContext.Provider>
  )
}

export function useNavigationBlocker() {
  return useContext(NavigationBlockerContext)
}
'use client'

import { createContext, useState, useContext } from 'react'

export const NavigationBlockerContext = createContext({
  isBlocked: false,
  setIsBlocked: () => {},
})

export function NavigationBlockerProvider({ children }) {
  const [isBlocked, setIsBlocked] = useState(false)

  return (
    <NavigationBlockerContext.Provider value={{ isBlocked, setIsBlocked }}>
      {children}
    </NavigationBlockerContext.Provider>
  )
}

export function useNavigationBlocker() {
  return useContext(NavigationBlockerContext)
}

创建一个使用该上下文的表单组件：

'use client'

import { useNavigationBlocker } from '../contexts/navigation-blocker'

export default function Form() {
  const { setIsBlocked } = useNavigationBlocker()

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        setIsBlocked(false)
      }}
      onChange={() => setIsBlocked(true)}
    >
      <input type="text" name="name" />
      <button type="submit">Save</button>
    </form>
  )
}
'use client'

import { useNavigationBlocker } from '../contexts/navigation-blocker'

export default function Form() {
  const { setIsBlocked } = useNavigationBlocker()

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        setIsBlocked(false)
      }}
      onChange={() => setIsBlocked(true)}
    >
      <input type="text" name="name" />
      <button type="submit">Save</button>
    </form>
  )
}

创建一个自定义的 Link 组件来阻止导航：

'use client'

import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'

interface CustomLinkProps extends React.ComponentProps<typeof Link> {
  children: React.ReactNode
}

export function CustomLink({ children, ...props }: CustomLinkProps) {
  const { isBlocked } = useNavigationBlocker()

  return (
    <Link
      onNavigate={(e) => {
        if (
          isBlocked &&
          !window.confirm('You have unsaved changes. Leave anyway?')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}
'use client'

import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'

export function CustomLink({ children, ...props }) {
  const { isBlocked } = useNavigationBlocker()

  return (
    <Link
      onNavigate={(e) => {
        if (
          isBlocked &&
          !window.confirm('You have unsaved changes. Leave anyway?')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}

创建一个导航组件：

'use client'

import { CustomLink as Link } from './custom-link'

export default function Nav() {
  return (
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
    </nav>
  )
}
'use client'

import { CustomLink as Link } from './custom-link'

export default function Nav() {
  return (
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
    </nav>
  )
}

最后，在根布局中用 NavigationBlockerProvider 包裹你的应用，并在页面中使用这些组件：

import { NavigationBlockerProvider } from './contexts/navigation-blocker'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <NavigationBlockerProvider>{children}</NavigationBlockerProvider>
      </body>
    </html>
  )
}
import { NavigationBlockerProvider } from './contexts/navigation-blocker'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <NavigationBlockerProvider>{children}</NavigationBlockerProvider>
      </body>
    </html>
  )
}

然后在页面中使用 Nav 和 Form 组件：

import Nav from './components/nav'
import Form from './components/form'

export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>Welcome to the Dashboard</h1>
        <Form />
      </main>
    </div>
  )
}
import Nav from './components/nav'
import Form from './components/form'

export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>Welcome to the Dashboard</h1>
        <Form />
      </main>
    </div>
  )
}

当用户尝试在表单有未保存更改时使用 CustomLink 导航离开，系统会提示确认是否离开。

版本历史

版本变更内容
v15.3.0新增 onNavigate API
v13.0.0不再需要子 <a> 标签。提供了代码修改工具 来自动更新代码库。
v10.0.0指向动态路由的 href 属性会自动解析，不再需要 as 属性。
v8.0.0改进了预取性能。
v1.0.0引入 next/link。

Image（旧版）

使用旧版 Image 组件实现向后兼容的图片优化。

脚本 (Script)

使用内置的 `next/script` 组件优化 Next.js 应用中的第三方脚本。