跳到内容

headers

headers 是一个异步函数,允许你从服务器组件读取 HTTP 入站请求标头。

app/page.tsx
import { headers } from 'next/headers'
 
export default async function Page() {
  const headersList = await headers()
  const userAgent = headersList.get('user-agent')
}

参考

参数

headers 不接受任何参数。

返回值

headers 返回一个只读Web Headers 对象。

  • Headers.entries(): 返回一个 iterator,允许遍历此对象中包含的所有键/值对。
  • Headers.forEach(): 对此 Headers 对象中的每个键/值对执行一次提供的函数。
  • Headers.get(): 返回一个 String 序列,其中包含 Headers 对象中具有给定名称的标头的所有值。
  • Headers.has(): 返回一个布尔值,指示 Headers 对象是否包含某个标头。
  • Headers.keys(): 返回一个 iterator,允许你遍历此对象中包含的键/值对的所有键。
  • Headers.values(): 返回一个 iterator,允许你遍历此对象中包含的键/值对的所有值。

须知

  • headers 是一个异步函数,它返回一个 Promise。你必须使用 async/await 或 React 的 use 函数。
    • 在版本 14 及更早版本中,headers 是一个同步函数。为了帮助向后兼容,你仍然可以在 Next.js 15 中同步访问它,但此行为在未来将被弃用。
  • 由于 headers 是只读的,因此你无法 setdelete 出站请求标头。
  • headers 是一个 动态 API,其返回值无法提前知晓。在路由中使用它将使路由选择动态渲染

示例

使用 Authorization header

app/page.js
import { headers } from 'next/headers'
 
export default async function Page() {
  const authorization = (await headers()).get('authorization')
  const res = await fetch('...', {
    headers: { authorization }, // Forward the authorization header
  })
  const user = await res.json()
 
  return <h1>{user.name}</h1>
}

版本历史

版本变更
v15.0.0-RCheaders 现在是一个异步函数。一个 codemod 可用。
v13.0.0引入 headers