v3
GitHub

<NuxtLink>

源码
Nuxt 提供了 <NuxtLink> 组件，用于处理应用程序中的各种链接。
<NuxtLink> 是 Vue Router 的 <RouterLink> 组件和 HTML 的 <a> 标签的替代方案。它能智能判断链接是内部链接还是外部链接，并依据情况优化渲染（预取、默认属性等）。

内部路由

在此示例中，我们使用 <NuxtLink> 组件链接到应用的另一页面。

<template>
  <NuxtLink to="/about">关于页面</NuxtLink>
</template>

向动态路由传递参数

这个示例中，我们传递 id 参数链接到路由 ~/pages/posts/[id].vue。

<template>
  <NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
    文章 123
  </NuxtLink>
</template>
查看 Nuxt DevTools 中的 Pages 面板，可以看到路由名称及其可能接受的参数。

静态文件及跨应用链接处理

默认情况下，<NuxtLink> 使用 Vue Router 的客户端路由导航处理相对路由。链接到 /public 目录中的静态文件或同域的其他应用时，可能会出现意外的 404 错误，因为这些文件不属于客户端路由。在这种情况下，可以给 <NuxtLink> 添加 external 属性，以跳过 Vue Router 的内部路由机制。

external 属性显式表示该链接为外部链接，<NuxtLink> 会渲染为标准 HTML <a> 标签。这样即可确保链接正确跳转，绕过 Vue Router 的路由逻辑，直接指向目标资源。

链接静态文件

对于 /public 目录下的静态文件（如 PDF 或图片），可使用 external 属性确保链接正确解析。

pages/index.vue
<template>
  <NuxtLink to="/example-report.pdf" external>
    下载报告
  </NuxtLink>
</template>

链接跨应用 URL

链接同域的不同应用时，使用 external 属性确保正确跳转。

pages/index.vue
<template>
  <NuxtLink to="/another-app" external>
    前往另一个应用
  </NuxtLink>
</template>

使用 external 属性或依赖自动检测，能保证导航正常，避免意外的路由问题，并提升与静态资源或跨应用场景的兼容性。

外部路由

此示例中，使用 <NuxtLink> 组件链接至网站。

app.vue
<template>
  <NuxtLink to="https://nuxtjs.org">
    Nuxt 网站
  </NuxtLink>
  <!-- <a href="https://nuxtjs.org" rel="noopener noreferrer">...</a> -->
</template>

rel 和 noRel 属性

带有 target 属性或绝对链接（例如以 http://、https:// 或 // 开头的链接）默认会添加 rel="noopener noreferrer" 属性。

  • noopener 解决了旧浏览器中的安全漏洞。
  • noreferrer 保护用户隐私，不向链接站点发送 Referer 请求头。

这些默认设置不会对 SEO 产生负面影响，且被认为是最佳实践。

若需覆盖此行为，可使用 rel 或 noRel 属性。

app.vue
<template>
  <NuxtLink to="https://twitter.com/nuxt_js">
    Nuxt Twitter
  </NuxtLink>
  <!-- <a href="https://twitter.com/nuxt_js" rel="noopener noreferrer">...</a> -->

  <NuxtLink to="https://discord.nuxtjs.org" rel="noopener">
    Nuxt Discord
  </NuxtLink>
  <!-- <a href="https://discord.nuxtjs.org" rel="noopener">...</a> -->

  <NuxtLink to="/about" target="_blank">关于页面</NuxtLink>
  <!-- <a href="/about" target="_blank" rel="noopener noreferrer">...</a> -->
</template>

可通过 noRel 属性防止默认的 rel 属性被加在外链上。

app.vue
<template>
  <NuxtLink to="https://github.com/nuxt" no-rel>
    Nuxt GitHub
  </NuxtLink>
  <!-- <a href="https://github.com/nuxt">...</a> -->
</template>
noRel 和 rel 不能同时使用。rel 将被忽略。

预取链接

Nuxt 自动包含智能预取功能，默认检测链接的可视状态（出现在视口内或滚动时），预加载对应页面的 JavaScript，使页面在点击时立即可用。Nuxt 仅在浏览器空闲时加载资源，且在离线或网络仅为 2G 时跳过预取。

pages/index.vue
<NuxtLink to="/about" no-prefetch>关于页面不预取</NuxtLink>
<NuxtLink to="/about" :prefetch="false">关于页面不预取</NuxtLink>

自定义预取触发条件

从 v3.13.0 起，支持对应 <NuxtLink> 的自定义预取触发。使用 prefetchOn 属性控制预取时机。

<template>
  <NuxtLink prefetch-on="visibility">
    当链接变为可视时预取（默认）
  </NuxtLink>

  <NuxtLink prefetch-on="interaction">
    当链接被悬停或获得焦点时预取
  </NuxtLink>
</template>
  • visibility：当链接进入视口时预取。通过 Intersection Observer API 检测元素与视口的交叉情况，滚动到视口时触发预取。
  • interaction：当链接被鼠标悬停或聚焦时预取。监听 pointerenter 和 focus 事件，主动在用户有交互意图时提前加载资源。

你也可以使用对象形式来配置 prefetchOn：

<template>
  <NuxtLink :prefetch-on="{ interaction: true }">
    当悬停或聚焦时预取
  </NuxtLink>
</template>

通常你不想两者都启用！

<template>
  <NuxtLink :prefetch-on="{ visibility: true, interaction: true }">
    悬停/聚焦或变为可视时都会预取
  </NuxtLink>
</template>

该配置既监听元素进入视口，也监听 pointerenter 和 focus 事件，可能导致多余资源加载或重复预取，因两个触发条件在不同场景下均会预取相同资源。

启用跨源预取

通过在 nuxt.config 中设置 crossOriginPrefetch 选项启用跨源预取，借助Speculation Rules API实现。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})

全局禁用预取

你也可以全局开启/关闭针对所有链接的预取功能。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        prefetch: false,
      },
    },
  },
})

属性

RouterLink

当未使用 external 时，<NuxtLink> 支持所有 Vue Router 的 RouterLink 属性

  • to：任何 URL 或 Vue Router 的路由位置对象
  • custom：是否由 <NuxtLink> 使用 <a> 标签包裹内容。允许完全控制链接渲染及点击导航行为。行为与 Vue Router 的 custom 属性一致。
  • exactActiveClass：精确激活链接时应用的 class。行为同 Vue Router exactActiveClass 属性，默认 "router-link-exact-active"
  • activeClass：激活链接时应用的 class。行为同 Vue Router activeClass 属性，默认 "router-link-active"
  • replace：与 Vue Router 的 replace 属性相同，控制导航是否替换历史记录。
  • ariaCurrentValue：精确激活链接时应用的 aria-current 属性值。行为同 Vue Router 的对应属性。

NuxtLink

  • href：to 的别名，若两者同时使用，href 被忽略。
  • noRel：设置为 true 时，不为外链添加 rel 属性。
  • external：强制将链接渲染为 <a> 标签，而非 Vue Router 的 RouterLink。
  • prefetch：启用时，会预取视口内链接对应的中间件、布局及负载（若开启 payloadExtraction）。配合实验性选项 crossOriginPrefetch 使用。
  • prefetchOn：自定义预取触发方式。可选值为 interaction 和 visibility（默认）。也可传入对象，如 { interaction: true, visibility: true }。仅当 prefetch 开启且未设置 noPrefetch 时生效。
  • noPrefetch：禁用预取。
  • prefetchedClass：预取完成后应用的 class。

锚点

  • target：链接的 target 属性值。
  • rel：链接的 rel 属性值。默认对外链添加 "noopener noreferrer"。
默认设置可覆盖，如需更改请参见覆盖默认值。

覆盖默认值

在 Nuxt 配置中

你可以在 nuxt.config 里覆盖 <NuxtLink> 的默认配置。

这些选项未来可能移动到其他位置，如 app.config 或 app/ 目录下。
nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        // 默认值
        componentName: 'NuxtLink',
        externalRelAttribute: 'noopener noreferrer',
        activeClass: 'router-link-active',
        exactActiveClass: 'router-link-exact-active',
        prefetchedClass: undefined, // 可设置为任意字符串类名
        trailingSlash: undefined, // 可设为 'append' 或 'remove'
        prefetch: true,
        prefetchOn: { visibility: true } 
      }
    }
  }
})

自定义链接组件

也可以通过 defineNuxtLink 自定义链接组件并覆盖 <NuxtLink> 的默认行为。

components/MyNuxtLink.ts
export default defineNuxtLink({
  componentName: 'MyNuxtLink',
  /* 更多配置见下方签名 */
})

然后即可像平常一样使用 <MyNuxtLink /> 组件，拥有你新的默认配置。

defineNuxtLink 签名

interface NuxtLinkOptions {
  componentName?: string;
  externalRelAttribute?: string;
  activeClass?: string;
  exactActiveClass?: string;
  trailingSlash?: 'append' | 'remove'
  prefetch?: boolean
  prefetchedClass?: string
  prefetchOn?: Partial<{
    visibility: boolean
    interaction: boolean
  }>
}
function defineNuxtLink(options: NuxtLinkOptions): Component {}
  • componentName：组件名称，默认 NuxtLink。
  • externalRelAttribute：外链默认添加的 rel 属性值，默认 "noopener noreferrer"。设为空字符串可禁用。
  • activeClass：激活链接默认应用的 class，行为同 Vue Router 的 linkActiveClass。默认 "router-link-active"。
  • exactActiveClass：精确激活链接默认应用的 class，行为同 Vue Router 的 linkExactActiveClass。默认 "router-link-exact-active"。
  • trailingSlash：控制 href 是否添加（或移除）结尾斜杠。无效设置将被忽略。
  • prefetch：是否默认启用预取。
  • prefetchOn：默认预取触发策略的详细控制。
  • prefetchedClass：预取完成后应用的默认 class。
Read and edit a live example in Docs > Examples > Routing > Pages.