Skip to main content

headers

headers 函数允许你从 服务器组件 读取 HTTP 传入请求标头。

¥The headers function allows you to read the HTTP incoming request headers from a Server Component.

headers()​

该 API 扩展了 网页标头 API。它是只读的，这意味着你无法 set / delete 传出请求标头。

¥This API extends the Web Headers API. It is read-only, meaning you cannot set / delete the outgoing request headers.

import { headers } from 'next/headers'

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

  return <div>Referer: {referer}</div>
}
import { headers } from 'next/headers'

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

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

很高兴知道：

¥Good to know:

  • headers() 是一个 动态功能，其返回值无法提前得知。在布局或页面中使用它会在请求时选择进入 动态渲染 的路由。

    ¥headers() is a Dynamic Function whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into dynamic rendering at request time.

API 参考​

¥API Reference

const headersList = headers()

参数​

¥Parameters

headers 不带任何参数。

¥headers does not take any parameters.

返回​

¥Returns

headers 返回只读 网页标题 对象。

¥headers returns a read-only Web Headers object.

  • Headers.entries()：返回 iterator，允许遍历该对象中包含的所有键/值对。

    ¥Headers.entries(): Returns an iterator allowing to go through all key/value pairs contained in this object.

  • Headers.forEach()：对此 Headers 对象中的每个键/值对执行一次提供的函数。

    ¥Headers.forEach(): Executes a provided function once for each key/value pair in this Headers object.

  • Headers.get()：返回具有给定名称的 Headers 对象内标头的所有值的 String 序列。

    ¥Headers.get(): Returns a String sequence of all the values of a header within a Headers object with a given name.

  • Headers.has()：返回一个布尔值，说明 Headers 对象是否包含某个标头。

    ¥Headers.has(): Returns a boolean stating whether a Headers object contains a certain header.

  • Headers.keys()：返回 iterator，允许你浏览此对象中包含的键/值对的所有键。

    ¥Headers.keys(): Returns an iterator allowing you to go through all keys of the key/value pairs contained in this object.

  • Headers.values()：返回 iterator，允许你浏览该对象中包含的键/值对的所有值。

    ¥Headers.values(): Returns an iterator allowing you to go through all values of the key/value pairs contained in this object.

示例​

¥Examples

与数据获取一起使用​

¥Usage with Data Fetching

headers() 可以与 数据获取暂挂 结合使用。

¥headers() can be used in combination with Suspense for Data Fetching.

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

async function User() {
  const authorization = headers().get('authorization')
  const res = await fetch('...', {
    headers: { authorization }, // Forward the authorization header
  })
  const user = await res.json()

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

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

IP 地址​

¥IP Address

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

¥headers() can be used to get the IP address of the client.

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() 还可以读取：

¥In addition to x-forwarded-for, headers() can also read:

  • x-real-ip

  • x-forwarded-host

  • x-forwarded-port

  • x-forwarded-proto

版本历史​

¥Version History

版本变化
v13.0.0headers 推出。