headers

headers 是一个异步函数，允许您从服务端组件 (Server Component) 中读取 HTTP 传入请求的标头。

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 是只读的，您无法 set 或 delete 传出请求的标头。
• headers 是一个动态 API (Dynamic API)，其返回值无法提前预知。使用它将使路由选择**动态渲染 (dynamic rendering)**。

示例

使用 Authorization 标头

import { headers } from 'next/headers'

export default async function Page() {
  const authorization = (await headers()).get('authorization')
  const res = await fetch('...', {
    headers: { authorization }, // 转发 authorization 标头
  })
  const user = await res.json()

  return <h1>{user.name}</h1>
}

版本历史