headers

headers 函数允许您从服务端组件 (Server Component) 中读取 HTTP 传入请求头信息。

`headers()`

此 API 扩展了 Web Headers API。它是只读的，意味着您无法 set / delete 传出请求头。

import { headers } from 'next/headers'

export default function Page() {
  const headersList = headers()
  const referer = headersList.get('referer')

  return <div>Referer: {referer}</div>
}

须知:

headers() 是一个**动态函数 (Dynamic Function)，其返回值无法提前预知。在布局或页面中使用它会使路由在请求时启用动态渲染 (dynamic rendering)**。

API 参考

const headersList = headers()

参数

headers 不接受任何参数。

返回值

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

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

示例

与数据获取结合使用

headers() 可以与 Suspense 数据获取 (Suspense for Data Fetching) 结合使用。

app/page.js

import { Suspense } from 'react'
import { headers } from 'next/headers'

async function User() {
  const authorization = headers().get('authorization')
  const res = await fetch('...', {
    headers: { authorization }, // 转发授权头部
  })
  const user = await res.json()

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

export default function Page() {
  return (
    <Suspense fallback={null}>
      <User />
    </Suspense>
  )
}

IP 地址

headers() 可用于获取客户端的 IP 地址。

app/page.js

import { Suspense } from 'react'
import { headers } from 'next/headers'

function IP() {
  const FALLBACK_IP_ADDRESS = '0.0.0.0'
  const forwardedFor = headers().get('x-forwarded-for')

  if (forwardedFor) {
    return forwardedFor.split(',')[0] ?? FALLBACK_IP_ADDRESS
  }

  return headers().get('x-real-ip') ?? FALLBACK_IP_ADDRESS
}

export default function Page() {
  return (
    <Suspense fallback={null}>
      <IP />
    </Suspense>
  )
}

除了 x-forwarded-for，headers() 还可以读取：

x-real-ip
x-forwarded-host
x-forwarded-port
x-forwarded-proto

版本历史

版本	变更
`v13.0.0`	引入 `headers` 函数。

On this page