usePathname
usePathname hook 的 API 参考。
usePathname 是一个 Client Component hook,可让你读取当前 URL 的 pathname。
'use client'
import { usePathname } from 'next/navigation'
export default function ExampleClientComponent() {
const pathname = usePathname()
return <p>Current pathname: {pathname}</p>
}'use client'
import { usePathname } from 'next/navigation'
export default function ExampleClientComponent() {
const pathname = usePathname()
return <p>Current pathname: {pathname}</p>
}usePathname 刻意要求使用 Client Component。需要注意的是,Client Component 并不是一种性能退化。它们是 Server Components 架构中不可或缺的一部分。
例如,带有 usePathname 的 Client Component 会在初始页面加载时被渲染为 HTML。当导航到新路由时,该组件无需重新获取。相反,该组件只下载一次(在客户端 JavaScript bundle 中),然后根据当前状态重新渲染。
小知识:
- 不支持从 Server Component 读取当前 URL。这一设计是有意为之,目的是支持在页面导航之间保留布局状态。
- 如果你的页面是静态预渲染的,并且你的应用在
next.config中配置了 rewrites 或使用了 Proxy 文件,那么使用usePathname()读取 pathname 可能会导致 hydration 不匹配错误,因为初始值来自服务端,可能与路由之后实际的浏览器 pathname 不一致。请参阅我们的示例以了解缓解此问题的方法。
<details>
<summary>与 Pages Router 的兼容性</summary>
如果你有使用 usePathname 的组件,并且它们被导入到 Pages Router 中的路由里,请注意,如果 router 尚未初始化,usePathname 可能会返回 null。这种情况可能发生在 fallback 路由 或 Pages Router 的自动静态优化过程中。
为了提升两种路由系统之间的兼容性,如果你的项目同时包含 app 和 pages 目录,Next.js 会自动调整 usePathname 的返回类型。
</details>
参数#
const pathname = usePathname()usePathname 不接受任何参数。
返回值#
usePathname 返回一个字符串,表示当前 URL 的 pathname。例如:
| URL | Returned value |
|---|---|
/ | '/' |
/dashboard | '/dashboard' |
/dashboard?v=2 | '/dashboard' |
/blog/hello-world | '/blog/hello-world' |
行为#
Cache Components#
当启用 cacheComponents 时,usePathname 可能需要一个 Suspense 边界。这取决于 pathname 能否在预渲染期间解析。
- 静态路由以及带有
generateStaticParams的路由:每个路由片段(包括动态参数)在构建时都是已知的。pathname 可以在预渲染期间解析,因此usePathname会在服务端解析,无需Suspense边界。 - 动态参数未被
generateStaticParams覆盖的路由:该参数是一个 fallback 参数,直到请求时才知道。pathname 无法在预渲染期间解析,因此usePathname会挂起(suspend)。请将该组件(或其父组件)包裹在Suspense边界中,以便其 fallback 可以在预渲染期间渲染;否则,构建会失败。
即使调用 usePathname 的组件本身是静态的,这也同样适用。例如,在 layout 中渲染的带有激活链接的侧边栏,会在其下方任何具有未知动态参数的页面上挂起。为了让 layout 的其余部分保持预渲染,请将调用 usePathname 的组件(或其父组件)包裹在带有 fallback 的 Suspense 边界中。
请参阅 Next.js 在 Suspense 之外的 Client Component 中遇到 URL 数据 以了解完整的修复方案和权衡。
示例#
响应路由变化执行操作#
'use client'
import { useEffect } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'
function ExampleClientComponent() {
const pathname = usePathname()
const searchParams = useSearchParams()
useEffect(() => {
// 在此处执行操作……
}, [pathname, searchParams])
}'use client'
import { useEffect } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'
function ExampleClientComponent() {
const pathname = usePathname()
const searchParams = useSearchParams()
useEffect(() => {
// 在此处执行操作……
}, [pathname, searchParams])
}避免 rewrites 导致的 hydration 不匹配#
当页面被预渲染时,会为其路径生成 HTML,例如 app/blog/[slug]/page.tsx 对应 /blog/hello。如果 next.config 中的 rewrite 或 Proxy 以不同的 URL 提供该页面,浏览器会保留其请求的 URL,而 usePathname() 在客户端读取的是该浏览器 URL,而不是 rewrite 的目标地址。
为避免 hydration 不匹配,请设计 UI,使只有一小部分隔离的区域依赖客户端 pathname。在服务端渲染一个稳定的 fallback,并在挂载后更新该部分。延迟读取会在真实 pathname 出现之前短暂显示 fallback;请参阅防止 hydration 前的闪烁以了解消除可见闪烁的技巧。
'use client'
import { useEffect, useState } from 'react'
import { usePathname } from 'next/navigation'
export default function PathnameBadge() {
const pathname = usePathname()
const [clientPathname, setClientPathname] = useState('')
useEffect(() => {
setClientPathname(pathname)
}, [pathname])
return (
<p>
Current pathname: <span>{clientPathname}</span>
</p>
)
}'use client'
import { useEffect, useState } from 'react'
import { usePathname } from 'next/navigation'
export default function PathnameBadge() {
const pathname = usePathname()
const [clientPathname, setClientPathname] = useState('')
useEffect(() => {
setClientPathname(pathname)
}, [pathname])
return (
<p>
Current pathname: <span>{clientPathname}</span>
</p>
)
}| Version | Changes |
|---|---|
v13.0.0 | 引入 usePathname。 |